Migration to Expressive 3.0

Expressive 3.0 should not result in many upgrade problems for users. However, starting in this version, we offer a few changes affecting the following that you should be aware of, and potentially update your application to adopt:

PHP 7.1 support

Starting in Expressive 3.0 we support only PHP 7.1+.

PSR-15 Support

All middleware and delegators now implement interfaces from PSR-15 instead of http-interop/http-middleware (a PSR-15 precursor). This means the following changes were made throughout Expressive:

This change also affects all middleware you, as an application developer, have written, and your middleware will need to be update. We provide a tool for this via zend-expressive-tooling. Make sure that package is up-to-date (a version 1 release should be installed), and run the following:

$ ./vendor/bin/expressive migrate:interop-middleware

This tool will locate any http-interop middleware and update it to PSR-15 middleware.

New dependencies

Expressive adds the following packages as dependencies:

New features

The following classes were added in version 3:

Signature and behavior changes

The following signature changes were made that could affect class extensions and/or consumers.


Zend\Expressive\Application was refactored dramatically for version 3.

If you were instantiating it directly previously, the constructor arguments are now, in order:

Application no longer supports piping or routing to double-pass middleware. If you continue to need double-pass middleware (e.g., defined by a third-party library), use Zend\Stratigility\doublePassMiddleware() to decorate it prior to piping or routing to it:

use Zend\Diactoros\Response;
use function Zend\Stratigility\doublePassMiddleware;

$app->pipe(doublePassMiddleware($someDoublePassMiddleware, new Response()));

$app->get('/foo', doublePassMiddleware($someDoublePassMiddleware, new Response()));

Additionally, the following methods were removed:


Zend\Expressive\Container\ApplicationFactory no longer looks at the zend-expressive.programmatic_pipeline flag, nor does it inject pipeline middleware and/or routed middleware from configuration any longer.

If you want to use configuration-driven pipelines and/or middleware, you may register the new class Zend\Expressive\Container\ApplicationConfigInjectionDelegator as a delegator factory on the Zend\Expressive\Application service.


Zend\Expressive\Container\NotFoundHandlerFactory now returns an instance of Zend\Expressive\Handler\NotFoundHandler, instead of Zend\Expressive\Middleware\NotFoundHandler (which has been removed).


Zend\Expressive\Middleware\LazyLoadingMiddleware now composes a Zend\Expressive\MiddlewareContainer instance instead of a more general PSR-11 container; this is to ensure that the value returned is a PSR-15 MiddlewareInterface instance.

Removed classes and traits


We provide a package you can add to your existing v2 application in order to upgrade it to version 3.

Before installing and running the migration tooling, make sure you have checked in your latest changes (assuming you are using version control), or have a backup of your existing code.

Install the migration tooling using the following command:

$ composer require --dev zendframework/zend-expressive-migration

Once installed, run the following command to migrate your application:

$ ./vendor/bin/expressive-migration migrate

This package does the following:

These steps should take care of most migration tasks.

It does not update unit tests. These cannot be automatically updated, due to the amount of variance in testing strategies.

When done, use a diffing tool to compare and verify all changes. Please be aware that the tool is not designed for edge cases; there may be things it does not do or cannot catch within your code. When unsure, refer to the other sections in this document to determine what else you may need to change.