Migrating from version 2 to version 3

In this document, we outline the backwards breaking changes with version 3.0, and provide guidance on how to upgrade your application to be compatible.

PHP support

We now support only PHP versions 7.1 and above. PHP 5.6 and 7.0 support has been dropped.


Stratigility now supports only PSR-15 interfaces. Support of http-interop/http-middleware has been dropped.

All middleware and request handlers must now implement PSR-15 interfaces, including those Stratigility implements.

As a result, a number of signatures have been changed. Primarily, these were a matter of updating typehints on Interop\Http\ServerMiddleware\DelegateInterface (defined in http-interop/http-middleware 0.4 and up, an early draft of PSR-15) and Interop\Http\Server\RequestHandlerInterface (defined in http-interop/http-server-handler, the immediate predecessor to the final spec) to Psr\Http\Server\RequestHandlerInterface, and adding the return type hint Psr\Http\Message\ResponseInterface.

Signatures affected include:

All of these classes now implement the PSR-15 MiddlewareInterface.

Pipeline - MiddlewarePipe

We now only allow piping Psr\Http\Server\MiddlewareInterface instances into the MiddlewarePipe class.

In version 2, we had a number of internal utilities for identifying other types of middleware (callable, double-pass, etc.), and would decorate those within the pipe() method. This is no longer allowed.

If you wish to use those types, you will need to decorate them using the appropriate decorators as outlined in the Class additions section.

Additionally, MiddlewarePipe is now marked final, and may not be directly extended. Decorate an instance if you wish to provide alternate behavior, or create your own MiddlewareInterface implementation to provide alternate internal logic.

Changes in public interfaces

Signature changes

Class additions

// Segregate to hosts matching 'example.com':
$pipeline->pipe(new HostMiddlewareDecorator('example.com', $middleware));

Alternately, use the host() utility function to generate the instance; see below.

// Segregate to paths matching '/foo' as the prefix:
$pipeline->pipe(new PathMiddlewareDecorator('/foo', $middleware));

Alternately, use the path() utility function to generate the instance; see below.

$pipeline->pipe(new CallableMiddlewareDecorator(function ($req, $handler) {
    // do some work
    $response = $next($req, $handler);
    // do some work
    return $response;

The arguments and return value can be type-hinted, but do not need to be. The decorator provides some checking on the return value in order to raise an exception if a response is not returned.

Alternately, use the middleware() utility function to generate the instance; see below.

$pipeline->pipe(new DoublePassMiddlewareDecorator(function ($req, $res, $next) {
    // do some work
    $response = $next($req, $res);
    // do some work
    return $response;

Per recommendations in previous versions, if you are using double-pass middleware, do not operate on the response passed to the middleware; instead, only operate on the response returned by $next, or produce a concrete response yourself.

Alternately, use the doublePassMiddleware() utility function to create the instance; see below.

Removed classes and exceptions

The following classes have been removed:

The following exceptions have been removed:

Removed methods

Function additions

Release 3.0 adds the following utility functions:


function Zend\Stratigility\host(
  string $host,
  Psr\Http\Server\MiddlewareInterface $middleware
) : Zend\Stratigility\Middleware\HostMiddlewareDecorator

This is a convenience wrapper around instantiation of a Zend\Stratigility\Middleware\HostMiddlewareDecorator instance:

$pipeline->pipe(host('example.com', $middleware));


function Zend\Stratigility\path(
  string $pathPrefix,
  Psr\Http\Server\MiddlewareInterface $middleware
) : Zend\Stratigility\Middleware\PathMiddlewareDecorator

This is a convenience wrapper around instantiation of a Zend\Stratigility\Middleware\PathMiddlewareDecorator instance:

$pipeline->pipe(path('/foo', $middleware));


function Zend\Stratigility\middleware(
    callable $middleware
) : Zend\Stratigility\Middleware\CallableMiddlewareDecorator

middleware() provides a convenient way to decorate callable middleware that implements the PSR-15 middleware signature when piping it to your application.

$pipeline->pipe(middleware(function ($request, $handler) {
  // ...


function Zend\Stratigility\doublePassMiddleware(
    callable $middleware,
    Psr\Http\Message\ResponseInterface $responsePrototype = null
) : Zend\Stratigility\Middleware\DoublePassMiddlewareDecorator

doublePassMiddleware() provides a convenient way to decorate middleware that implements the double pass middleware signature when piping it to your application.

$pipeline->pipe(doublePassMiddleware(function ($request, $response, $next) {
  // ...

If you are not using zend-diactoros as a PSR-7 implementation, you will need to pass a response prototype as well:

$pipeline->pipe(doublePassMiddleware(function ($request, $response, $next) {
  // ...
}, $response);