Document middleware listener

Author: weierophinney

doc/book/intro.md

@@ -244,6 +244,8 @@ Once you've done this, there are two additional actions you can take. The first
 the application. In the default implementation, this does the following:
 
 - Attaches the default route listener (`Zend\Mvc\RouteListener`).
+- Attaches the middleware dispatch listener (`Zend\Mvc\MiddlewareListener`)
+  (v2.7.0 and up).
 - Attaches the default dispatch listener (`Zend\Mvc\DispatchListener`).
 - Attaches the `ViewManager` listener (`Zend\Mvc\View\ViewManager`).
 - Creates the `MvcEvent`, and injects it with the application, request, and

doc/book/middleware.md

@@ -0,0 +1,108 @@
+# Dispatching PSR-7 Middleware
+
+[PSR-7](http://www.php-fig.org/psr/psr-7/) defines interfaces for HTTP messages,
+and is now being adopted by many frameworks; Zend Framework itself offers a
+parallel microframework targeting PSR-7 with [Expressive](https://zendframework.github.io/zend-expressive).
+What if you want to dispatch PSR-7 middleware from zend-mvc?
+
+zend-mvc currently uses [zend-http](https://github.com/zendframework/zend-http)
+for its HTTP transport layer, and the objects it defines are not compatible with
+PSR-7, meaning the basic MVC layer does not and cannot make use of PSR-7
+currently.
+
+However, starting with version 2.7.0, zend-mvc offers
+`Zend\Mvc\MiddlewareListener`. This [dispatch](mvc-event.md#mvceventevent_dispatch-dispatch)
+listener listens prior to the default `DispatchListener`, and executes if the
+route matches contain a "middleware" parameter, and the service that resolves to
+is callable. When those conditions are met, it uses the [PSR-7 bridge](https://github.com/zendframework/zend-psr7bridge)
+to convert the zend-http request and response objects into PSR-7 instances, and
+then invokes the middleware.
+
+## Mapping routes to middleware
+
+The first step is to map a route to PSR-7 middleware. This looks like any other
+[routing](routing.md) configuration, with one small change: instead of providing
+a "controller" in the routing defaults, you provide "middleware":
+
+```php
+// Via configuration:
+return [
+    'router' => 
+        'routes' => [
+            'home' => [
+                'type' => 'literal',
+                'options' => [
+                    'route' => '/',
+                    'defaults' => [
+                        'middleware' => 'Application\Middleware\IndexMiddleware',
+                    ],
+                ],
+            ],
+        ],
+    ],
+];
+
+// Manually:
+$route = Literal::factory([
+    'route' => '/',
+    'defaults' => [
+        'middleware' => 'Application\Middleware\IndexMiddleware',
+    ],
+]);
+```
+
+Middleware may be provided as PHP callables, or as service names.
+
+> ### No action required
+>
+> Unlike action controllers, middleware typically is single purpose, and, as
+> such, does require a default `action` parameter.
+
+## Middleware services
+
+In a normal zend-mvc dispatch cycle, controllers are pulled from a dedicated
+`ControllerManager`. Middleware, however, are pulled from the application
+service manager.
+
+Middleware retrieved *must* be PHP callables. The `MiddlewareListener` will
+create an error response if non-callable middleware is indicated.
+
+## Writing middleware
+
+When dispatching middleware, the `MiddlewareListener` calls it with two
+arguments, the PSR-7 request and response, respectively. As such, your
+middleware signature should look like the following:
+
+```php
+namespace Application\Middleware;
+
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+
+class IndexMiddleware
+{
+    public function __invoke(ServerRequestInterface $request, ResponseInterface $response)
+    {
+        // do some work
+    }
+}
+```
+
+From there, you can pull information from the composed request, and manipulate
+the response.
+
+> ### Routing parameters
+>
+> At the time of the 2.7.0 release, route match parameters are not yet injected
+> into the PSR-7 `ServerRequest` instance, and are thus not available as request
+> attributes..
+
+## Middleware return values
+
+Ideally, your middleware should return a PSR-7 response. When it does, it is
+converted back to a zend-http response and returned by the `MiddlewareListener`,
+causing the application to short-circuit and return the response immediately.
+
+You can, however, return arbitrary values. If you do, the result is pushed into
+the `MvcEvent` as the event result, allowing later dispatch listeners to
+manipulate the results.

doc/book/migration.md

@@ -2,6 +2,13 @@
 
 ## Upgrading to 2.7
 
+### Middleware
+
+zend-mvc now registers `Zend\Mvc\MiddlewareListener` as a dispatch listener at
+a priority higher than `Zend\Mvc\DispatchListener`, allowing dispatch of
+[PSR-7](http://www.php-fig.org/psr/psr-7/) middleware. Read the
+[middleware chapter](middleware.md) for details on how to use this new feature.
+
 ### Application
 
 The constructor signature of `Zend\Mvc\Application` has changed. Previously, it

doc/book/mvc-event.md

@@ -138,11 +138,13 @@ Class                                        | Priority | Method Called
 
 #### All contexts
 
-The following listeners are attached for all contexts:
+The following listeners are attached for all contexts (sorted from higher
+priority to lower priority):
 
 Class                         | Priority | Method Called | Triggers | Description
 ------------------------------|---------:|---------------|----------|------------
-`Zend\Mvc\DispatchListener`   | 1        | `onDispatch`  | `MvcEvent::EVENT_DISPATCH_ERROR` (if an exception is raised during dispatch processes) | Try to load the matched controller from the service manager (and throws various exceptions if it does not).
+`Zend\Mvc\MiddlewareListener` | 1        | `onDispatch`  | `MvcEvent::EVENT_DISPATCH_ERROR` (if an exception is raised during dispatch processes) | Load and dispatch the matched PSR-7 middleware from the service manager (and throws various exceptions if it does not).
+`Zend\Mvc\DispatchListener`   | 1        | `onDispatch`  | `MvcEvent::EVENT_DISPATCH_ERROR` (if an exception is raised during dispatch processes) |  Load and dispatch the matched controller from the service manager (and throws various exceptions if it does not).
 `Zend\Mvc\AbstractController` | 1        | `onDispatch`  | none     | The `onDispatch` method of the `AbstractController` is an abstract method. In `AbstractActionController`, for instance, it calls the action method.
 
 ### Triggered By
@@ -192,11 +194,12 @@ Class                       | Priority | Method Called        | Description
 
 ### Triggered By
 
-Class                       | In Method
-----------------------------|----------
-`Zend\Mvc\DispatchListener` | `onDispatch`
-`Zend\Mvc\DispatchListener` | `marshallControllerNotFoundEvent`
-`Zend\Mvc\DispatchListener` | `marshallBadControllerEvent`
+Class                         | In Method
+------------------------------|----------
+`Zend\Mvc\MiddlewareListener` | `onDispatch`
+`Zend\Mvc\DispatchListener`   | `onDispatch`
+`Zend\Mvc\DispatchListener`   | `marshallControllerNotFoundEvent`
+`Zend\Mvc\DispatchListener`   | `marshallBadControllerEvent`
 
 ## `MvcEvent::EVENT_RENDER` ("render")
 

doc/book/services.md

@@ -77,6 +77,7 @@ services configured out of the box.
 ### Invokable services
 
 - `DispatchListener`, mapping to `Zend\Mvc\DispatchListener`.
+- `Zend\Mvc\MiddlewareListener`.
 - `RouteListener`, mapping to `Zend\Mvc\RouteListener`.
 - `SendResponseListener`, mapping to `Zend\Mvc\SendResponseListener`.
 - `SharedEventManager`, mapping to `Zend\EventManager\SharedEventManager`.
@@ -314,6 +315,7 @@ services configured out of the box.
 - `Configuration`, mapping to the `Config` service.
 - `Console`, mapping to the `ConsoleAdapter` service.
 - `Di`, mapping to the `DependencyInjector` service.
+- `MiddlewareListener`, mapping to the `Zend\Mvc\MiddlewareListener` service.
 - `Zend\Di\LocatorInterface`, mapping to the `DependencyInjector` service.
 - `Zend\EventManager\EventManagerInterface`, mapping to the `EventManager`
   service. This is mainly to ensure that when falling through to DI, classes

mkdocs.yml

@@ -12,6 +12,7 @@ pages:
       - 'Available Controllers': controllers.md
       - 'Controller Plugins': plugins.md
       - Examples: examples.md
+      - 'Dispatching PSR-7 Middleware': middleware.md
       - 'Migration Guide': migration.md
 site_name: zend-mvc
 site_description: 'zend-mvc: MVC application provider'