Based on https://github.com/zendframework/zend-expressive/releases/tag/3.0.0rc5 (commit d175c074191f457bab85187bfe2f25ea8a9e9acc in this repo)
**This release contains a breaking change.**
This release updates to mezzio-router 3.0.0rc5, which renames
`Mezzio\Router\Middleware\PathBasedRoutingMiddleware` to
`Mezzio\Router\RouteCollector`, and drops its extension of
`RouteMiddleware`. This was done to prevent confusion between the two
route middleware implementations in the final release, and because the
primariy duty of the (newly renamed) `RouteCollector` is to produce and
inject `Route` instances into the composed router.
This release of mezzio required one change to comply:
`Mezzio\Application` now composes a `RouteCollector` instead of
a `PathBasedRoutingMiddleware` instance.
Below is a cumulative list of changes for the 3.0.0 release, including
all changes from previous alpha and RC releases. References to
`PathBasedRoutingMiddleware` have been updated to reference
`RouteCollector` or `RouteMiddleware` based on context:
Added
-----
- [zendframework/zend-expressive#543](https://github.com/zendframework/zend-expressive/pull/543) adds support
for the final PSR-15 interfaces, and explicitly depends on
psr/http-server-middleware.
- [zendframework/zend-expressive#538](https://github.com/zendframework/zend-expressive/pull/538) adds scalar
and return type hints to methods wherever possible.
- [zendframework/zend-expressive#562](https://github.com/zendframework/zend-expressive/pull/562) adds the
class `Mezzio\Response\ServerRequestErrorResponseGenerator`, and maps
it to the `Mezzio\Container\ServerRequestErrorResponseGeneratorFactory`.
The class generates an error response when an exeption occurs producing a
server request instance, and can be optionally templated.
- [zendframework/zend-expressive#543](https://github.com/zendframework/zend-expressive/pull/543) adds a new
class, `Mezzio\MiddlewareContainer`. The class decorates a PSR-11
`ContainerInterface`, and adds the following behavior:
- If a class is not in the container, but exists, `has()` will return `true`.
- If a class is not in the container, but exists, `get()` will attempt to
instantiate it, caching the instance locally if it is valid.
- Any instance pulled from the container or directly instantiated is tested.
If it is a PSR-15 `RequestHandlerInterface`, it will decorate it in a
laminas-stratigility `RequestHandlerMiddleware` instance. If the instance is
not a PSR-15 `MiddlewareInterface`, the container will raise a
`Mezzio\Exception\InvalidMiddlewareException`.
- [zendframework/zend-expressive#543](https://github.com/zendframework/zend-expressive/pull/543) adds a new
class, `Mezzio\MiddlewareFactory`. The class composes a
`MiddlewareContainer`, and exposes the following methods:
- `callable(callable $middleware) : CallableMiddlewareDecorator`
- `handler(RequestHandlerInterface $handler) : RequestHandlerMiddleware`
- `lazy(string $service) : LazyLoadingMiddleware`
- `prepare($middleware) : MiddlewareInterface`: accepts a string service name,
callable, `RequestHandlerInterface`, `MiddlewareInterface`, or array of such
values, and returns a `MiddlewareInterface`, raising an exception if it
cannot determine what to do.
- `pipeline(...$middleware) : MiddlewarePipe`: passes each argument to
`prepare()`, and the result to `MiddlewarePipe::pipe()`, returning the
pipeline when complete.
- [zendframework/zend-expressive#543](https://github.com/zendframework/zend-expressive/pull/543) adds
the following factory classes, each within the `Mezzio\Container`
namespace:
- `ApplicationPipelineFactory`: creates and returns a
`Laminas\Stratigility\MiddlewarePipe` to use as the application middleware
pipeline.
- `DispatchMiddlewareFactory`: creates and returns a `Mezzio\Router\DispatchMiddleware` instance.
- `EmitterFactory`: creates and returns a
`Laminas\HttpHandlerRunner\Emitter\EmitterStack` instance composing an
`SapiEmitter` from that same namespace as the only emitter on the stack.
This is used as a dependency for the `Laminas\HttpHandlerRunner\RequestHandlerRunner`
service.
- `MiddlewareContainerFactory`: creates and returns a `Mezzio\MiddlewareContainer`
instance decorating the PSR-11 container passed to the factory.
- `MiddlewareFactoryFactory`: creates and returns a `Mezzio\MiddlewareFactory`
instance decorating a `MiddlewareContainer` instance as pulled from the
container.
- `RequestHandlerRunnerFactory`: creates and returns a
`Laminas\HttpHandlerRunner\RequestHandlerRunner` instance, using the services
`Mezzio\Application`, `Laminas\HttpHandlerRunner\Emitter\EmitterInterface`,
`Mezzio\ServerRequestFactory`, and `Mezzio\ServerRequestErrorResponseGenerator`.
- `ServerRequestFactoryFactory`: creates and returns a `callable` factory for
generating a PSR-7 `ServerRequestInterface` instance; this returned factory is a
dependency for the `Laminas\HttpHandlerRunner\RequestHandlerRunner` service.
- `ServerRequestErrorResponseGeneratorFactory`: creates and returns a
`callable` that accepts a PHP `Throwable` in order to generate a PSR-7
`ResponseInterface` instance; this returned factory is a dependency for the
`Laminas\HttpHandlerRunner\RequestHandlerRunner` service, which uses it to
generate a response in the scenario that the `ServerRequestFactory` is
unable to create a request instance.
- [zendframework/zend-expressive#551](https://github.com/zendframework/zend-expressive/pull/551) and
[zendframework/zend-expressive#554](https://github.com/zendframework/zend-expressive/pull/554) add
the following constants under the `Mezzio` namespace:
- `DEFAULT_DELEGATE` can be used to refer to the former `DefaultDelegate` FQCN
service, and maps to the `Mezzio\Handler\NotFoundHandler` service.
- `IMPLICIT_HEAD_MIDDLEWARE` can be used to refer to the former
`Mezzio\Middleware\ImplicitHeadMiddleware` service, and maps to the
`Mezzio\Router\Middleware\ImplicitHeadMiddleware` service.
- `IMPLICIT_OPTIONS_MIDDLEWARE` can be used to refer to the former
`Mezzio\Middleware\ImplicitOptionsMiddleware` service, and maps to the
`Mezzio\Router\Middleware\ImplicitOptionsMiddleware` service.
- `NOT_FOUND_MIDDLEWARE` can be used to refer to the former
`Mezzio\Middleware\NotFoundMiddleware` service, and maps to the
`Mezzio\Handler\NotFoundHandler` service.
Changed
-------
- [zendframework/zend-expressive#579](https://github.com/zendframework/zend-expressive/pull/579) updates the
version constraint for mezzio-router to use 3.0.0rc4 or later.
- [zendframework/zend-expressive#579](https://github.com/zendframework/zend-expressive/pull/579) updates the
version constraint for laminas-stratigility to use 3.0.0rc1 or later.
- [zendframework/zend-expressive#543](https://github.com/zendframework/zend-expressive/pull/543) adds
a dependency on laminas/laminas-httphandlerrunner 1.0.0
- [zendframework/zend-expressive#542](https://github.com/zendframework/zend-expressive/pull/542) modifies the
`composer.json` to no longer suggest the pimple/pimple package, but rather the
laminas/laminas-pimple-config package.
- [zendframework/zend-expressive#542](https://github.com/zendframework/zend-expressive/pull/542) modifies the
`composer.json` to no longer suggest the aura/di package, but rather the
laminas/laminas-auradi-config package.
- [zendframework/zend-expressive#543](https://github.com/zendframework/zend-expressive/pull/543) updates the
`Mezzio\ConfigProvider` to reflect new, removed, and updated services
and their factories.
- [zendframework/zend-expressive#554](https://github.com/zendframework/zend-expressive/pull/554) updates
the `ConfigProvider` to add entries for the following constants as follows:
- `IMPLICIT_HEAD_MIDDLEWARE` aliases to the `Mezzio\Router\Middleware\ImplicitHeadMiddleware` service.
- `IMPLICIT_OPTIONS_MIDDLEWARE` aliases to the `Mezzio\Router\Middleware\ImplicitOptionsMiddleware` service.
- [zendframework/zend-expressive#543](https://github.com/zendframework/zend-expressive/pull/543) updates
`Mezzio\Handler\NotFoundHandler` to implement the PSR-15
`RequestHandlerInterface`. As `Mezzio\Middleware\NotFoundHandler` is
removed, `Mezzio\Container\NotFoundHandlerFactory` has been
re-purposedto create an instance of `Mezzio\Handler\NotFoundHandler`.
- [zendframework/zend-expressive#561](https://github.com/zendframework/zend-expressive/pull/561) modifies the
`Mezzio\Handler\NotFoundHandler` to compose a response factory
instead of a response prototype.
- [zendframework/zend-expressive#543](https://github.com/zendframework/zend-expressive/pull/543) refactors
`Mezzio\Application` completely.
The class no longer extends `Laminas\Stratigility\MiddlewarePipe`, and instead
implements the PSR-15 `MiddlewareInterface` and `RequestHandlerInterface`.
It now **requires** the following dependencies via constructor injection, in
the following order:
- `Mezzio\MiddlewareFactory`
- `Laminas\Stratigility\MiddlewarePipe`; this is the pipeline representing the application.
- `Mezzio\Router\RouteCollector`
- `Laminas\HttpHandlerRunner\RequestHandlerRunner`
It removes all "getter" methods (as detailed in the "Removed" section of this
release), but retains the following methods, with the changes described below.
Please note: in most cases, these methods accept the same arguments as in the
version 2 series, with the exception of callable double-pass middleware (these
may be decorated manually using `Laminas\Stratigility\doublePassMiddleware()`),
and http-interop middleware (no longer supported; rewrite as PSR-15
middleware).
- `pipe($middlewareOrPath, $middleware = null) : void` passes its arguments to
the composed `MiddlewareFactory`'s `prepare()` method; if two arguments are
provided, the second is passed to the factory, and the two together are
passed to `Laminas\Stratigility\path()` in order to decorate them to work as
middleware. The prepared middleware is then piped to the composed
`MiddlewarePipe` instance.
As a result of switching to use the `MiddlewareFactory` to prepare
middleware, you may now pipe `RequestHandlerInterface` instances as well.
- `route(string $path, $middleware, array $methods = null, string $name) : Route`
passes its `$middleware` argument to the `MiddlewareFactory::prepare()`
method, and then all arguments to the composed `RouteCollector` instance's
`route()` method.
As a result of switching to use the `MiddlewareFactory` to prepare
middleware, you may now route to `RequestHandlerInterface` instances as
well.
- Each of `get`, `post`, `patch`, `put`, `delete`, and `any` now proxy to
`route()` after marshaling the correct `$methods`.
- `getRoutes() : Route[]` proxies to the composed `RouteCollector` instance.
- `handle(ServerRequestInterface $request) : ResponseInterface` proxies to the
composed `MiddlewarePipe` instance's `handle()` method.
- `process(ServerRequestInterface $request, RequestHandlerInterface $handler) : ResponseInterface`
proxies to the composed `MiddlewarePipe` instance's `process()` method.
- `run() : void` proxies to the composed `RequestHandlerRunner` instance.
Please note that the method no longer accepts any arguments.
- [zendframework/zend-expressive#543](https://github.com/zendframework/zend-expressive/pull/543) modifies the
`Mezzio\Container\ApplicationFactory` to reflect the changes to the
`Mezzio\Application` class as detailed above. It pulls the following
services to inject via the constructor:
- `Mezzio\MiddlewareFactory`
- `Laminas\Stratigility\ApplicationPipeline`, which should resolve to a
`MiddlewarePipe` instance; use the
`Mezzio\Container\ApplicationPipelineFactory`.
- `Mezzio\Router\RouteCollector`
- `Laminas\HttpHandlerRunner\RequestHandlerRunner`
- [zendframework/zend-expressive#581](https://github.com/zendframework/zend-expressive/pull/581)
changes how the `ApplicationConfigInjectionDelegator::injectPipelineFromConfig()`
method works. Previously, it would auto-inject routing and dispatch middleware
if routes were configured, but no `middleware_pipeline` was present.
Considering that this method will always be called manually, this
functionality was removed; the method now becomes a no-op if no
`middleware_pipeline` is present.
- [zendframework/zend-expressive#568](https://github.com/zendframework/zend-expressive/pull/568) updates the
`ErrorHandlerFactory` to pull the `Psr\Http\Message\ResponseInterface`
service, which returns a factory capable of returning a response instance,
and passes it to the `Laminas\Stratigility\Middleware\ErrorHandler` instance it
creates, as that class changes in 3.0.0alpha4 such that it now expects a
factory instead of an instance.
- [zendframework/zend-expressive#562](https://github.com/zendframework/zend-expressive/pull/562) extracts
most logic from `Mezzio\Middleware\ErrorResponseGenerator` to a new
trait, `Mezzio\Response\ErrorResponseGeneratorTrait`. A trait was
used as the classes consuming it are from different namespaces, and thus
different inheritance trees. The trait is used by both the
`ErrorResponseGenerator` and the new `ServerRequestErrorResponseGenerator`.
- [zendframework/zend-expressive#551](https://github.com/zendframework/zend-expressive/pull/551) removes
`Mezzio\Container\RouteMiddlewareFactory`, as mezzio-router
now provides a factory for the middleware.
- [zendframework/zend-expressive#551](https://github.com/zendframework/zend-expressive/pull/551) removes
`Mezzio\Container\DispatchMiddlewareFactory`, as mezzio-router
now provides a factory for the middleware.
- [zendframework/zend-expressive#551](https://github.com/zendframework/zend-expressive/pull/551) removes
`Mezzio\Middleware\ImplicitHeadMiddleware`, as it is now provided by
the mezzio-router package.
- [zendframework/zend-expressive#551](https://github.com/zendframework/zend-expressive/pull/551) removes
`Mezzio\Middleware\ImplicitOptionsMiddleware`, as it is now provided
by the mezzio-router package.
Deprecated
----------
- Nothing.
Removed
-------
- [zendframework/zend-expressive#529](https://github.com/zendframework/zend-expressive/pull/529) removes
support for PHP versions prior to PHP 7.1.
- [zendframework/zend-expressive#529](https://github.com/zendframework/zend-expressive/pull/529) removes
support for http-interop/http-middleware (previous PSR-15 iteration).
- [zendframework/zend-expressive#543](https://github.com/zendframework/zend-expressive/pull/543) removes
support for http-interop/http-server-middleware.
- [zendframework/zend-expressive#580](https://github.com/zendframework/zend-expressive/pull/580) removes
laminas-diactoros as a requirement; all usages of it within the package are
currently conditional on it being installed, and can be replaced easily with
any other PSR-7 implementation at this time.
- [zendframework/zend-expressive#543](https://github.com/zendframework/zend-expressive/pull/543) removes the
class `Mezzio\Delegate\NotFoundDelegate`; use
`Mezzio\Handler\NotFoundHandler` instead.
- [zendframework/zend-expressive#546](https://github.com/zendframework/zend-expressive/pull/546) removes the
service `Mezzio\Delegate\DefaultDelegate`, as there is no longer a
concept of a default handler invoked by the application. Instead, developers
MUST pipe a request handler or middleware at the innermost layer of the
pipeline guaranteed to return a response; we recommend using
`Mezzio\Handler\NotFoundHandler` for this purpose.
- [zendframework/zend-expressive#543](https://github.com/zendframework/zend-expressive/pull/543) removes the
class `Mezzio\Middleware\RouteMiddleware`. Use the
`RouteMiddleware` from mezzio-router instead.
- [zendframework/zend-expressive#543](https://github.com/zendframework/zend-expressive/pull/543) removes the
class `Mezzio\Middleware\DispatchMiddleware`. Use the
`DispatchMiddleware` from mezzio-router instead; the factory
`Mezzio\Container\DispatchMiddlewareFactory` will return an instance
for you.
- [zendframework/zend-expressive#543](https://github.com/zendframework/zend-expressive/pull/543) removes the
class `Mezzio\Emitter\EmitterStack`; use the class
`Laminas\HttpHandlerRunner\Emitter\EmitterStack` instead.
- [zendframework/zend-expressive#543](https://github.com/zendframework/zend-expressive/pull/543) removes the
following methods from `Mezzio\Application`:
- `pipeRoutingMiddleware()`: use `pipe(\Mezzio\Router\RouteMiddleware::class)` instead.
- `pipeDispatchMiddleware()`: use `pipe(\Mezzio\Router\DispatchMiddleware::class)` instead.
- `getContainer()`
- `getDefaultDelegate()`: ensure you pipe middleware or a request handler
capable of returning a response at the innermost layer;
`Mezzio\Handler\NotFoundHandler` can be used for this.
- `getEmitter()`: use the `Laminas\HttpHandlerRunner\Emitter\EmitterInterface` service from the container.
- `injectPipelineFromConfig()`: use the new `ApplicationConfigInjectionDelegator` and/or the static method of the same name it defines.
- `injectRoutesFromConfig()`: use the new `ApplicationConfigInjectionDelegator` and/or the static method of the same name it defines.
- [zendframework/zend-expressive#543](https://github.com/zendframework/zend-expressive/pull/543) removes the
class `Mezzio\AppFactory`.
Fixed
-----
- [zendframework/zend-expressive#574](https://github.com/zendframework/zend-expressive/pull/574) updates the
classes `Mezzio\Exception\InvalidMiddlewareException` and
`MissingDependencyException` to implement the
[PSR-11](https://www.php-fig.org/psr/psr-11/) `ContainerExceptionInterface`.