Merge branch 'hotfix/94'

Close #94

Author: weierophinney

CHANGELOG.md

@@ -6,7 +6,8 @@ All notable changes to this project will be documented in this file, in reverse
 
 ### Added
 
-- Nothing.
+- [#94](https://github.com/zendframework/zend-mvc/pull/94) adds a documentation
+  recipe for using middleware withing MVC event listeners.
 
 ### Deprecated
 

doc/book/cookbook/middleware-in-listeners.md

@@ -0,0 +1,62 @@
+# Using middleware within event listeners
+
+Within the MVC workflow, you can use middleware within event listeners by
+converting the request and response objects composed in the event to PSR-7
+equivalents using [zend-psr7bridge](https://github.com/zendframework/zend-psr7bridge).
+
+As an example, consider the following `AuthorizationMiddleware`:
+
+```php
+namespace Application\Middleware;
+
+use Psr\Http\Message\ServerRequestInterface as RequestInterface;
+use Psr\Http\Message\ResponseInterface;
+
+class AuthorizationMiddleware
+{
+    public function __invoke(RequestInterface $request, ResponseInterface $response, callable $next = null)
+    {
+        // handle authorization here...
+    }
+}
+```
+
+Since the request and response composed in `MvcEvent` instances are specifically
+from zend-http, we will use zend-psr7bridge to convert them to PSR-7
+equivalents. As an example, consider the following module declaration, which
+registers a `dispatch` listener to invoke the above middleware:
+
+```php
+namespace Application;
+
+use Psr\Http\Message\ResponseInterface;
+use Zend\Psr7Bridge\Psr7ServerRequest;
+use Zend\Psr7Bridge\Psr7Response;
+
+class Module
+{
+    public function onBootstrap($e)
+    {
+        $app          = $e->getApplication();
+        $eventManager = $app->getEventManager();
+        $services     = $app->getServiceManager();
+
+        $eventManager->attach($e::EVENT_DISPATCH, function ($e) use ($services) {
+            $request  = Psr7ServerRequest::fromZend($e->getRequest());
+            $response = Psr7Response::fromZend($e->getResponse());
+            $done     = function ($request, $response) {
+            };
+
+            $result   = ($services->get(Middleware\AuthorizationMiddleware::class))(
+                $request,
+                $response,
+                $done
+            );
+
+            if ($result) {
+                return Psr7Response::toZend($result);
+            }
+        }, 2);
+    }
+}
+```

doc/book/middleware.md

@@ -27,7 +27,7 @@ a "controller" in the routing defaults, you provide "middleware":
 ```php
 // Via configuration:
 return [
-    'router' => 
+    'router' =>
         'routes' => [
             'home' => [
                 'type' => 'literal',

mkdocs.yml

@@ -14,6 +14,8 @@ pages:
       - Examples: examples.md
       - 'Dispatching PSR-7 Middleware': middleware.md
       - 'Migration Guide': migration.md
+    - Cookbook:
+      - 'Using middleware within event listeners': cookbook/middleware-in-listeners.md
 site_name: zend-mvc
 site_description: 'zend-mvc: MVC application provider'
 repo_url: 'https://github.com/zendframework/zend-mvc'