Merging develop to master in preparation for 3.1.0 release

Author: weierophinney

CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to this project will be documented in this file, in reverse chronological order by release.
 
+## 3.1.0 - TBD
+
+### Added
+
+- [#217](https://github.com/zendframework/zend-mvc/pull/217) adds support for
+  middleware _pipelines_ when using the `MiddlewareListener`. You can now
+  specify an _array` of middleware for the `middleware` attached to a route, and
+  it will be marshaled into a `Zend\Stratigility\MiddlewarePipe` instance, using
+  the same rules as if you specified a single middleware.
+
+- [#236](https://github.com/zendframework/zend-mvc/pull/236) adds the ability to
+  attach dispatch listeners to middleware when using the `MiddlewareListener`.
+  Attach shared events to the class identifier `Zend\Mvc\Controller\MiddlewareController`.
+  This feature helps ensure that listeners that should run for every controller
+  (e.g., authentication or authorization listeners) will run even for
+  middleware.
+
+### Deprecated
+
+- Nothing.
+
+### Removed
+
+- [#211](https://github.com/zendframework/zend-mvc/pull/211) Removed unused
+  zend-servicemanager v2 and zend-eventmanager v2 compatibility code since
+  zend-mvc requires v3 of those components.
+
+### Fixed
+
+- Nothing.
+
 ## 3.0.5 - TBD
 
 ### Added

composer.json

@@ -27,7 +27,8 @@
         "phpunit/phpunit": "^6.0.7 || ^5.7.14",
         "zendframework/zend-coding-standard": "~1.0.0",
         "zendframework/zend-json": "^2.6.1 || ^3.0",
-        "zendframework/zend-psr7bridge": "^0.2"
+        "zendframework/zend-psr7bridge": "^0.2",
+        "zendframework/zend-stratigility": "^2.0.1"
     },
     "suggest": {
         "zendframework/zend-json": "(^2.6.1 || ^3.0) To auto-deserialize JSON body content in AbstractRestfulController extensions, when json_decode is unavailable",
@@ -40,7 +41,8 @@
         "zendframework/zend-mvc-plugin-prg": "To provide Post/Redirect/Get functionality within controllers",
         "zendframework/zend-paginator": "^2.7 To provide pagination functionality via PaginatorPluginManager",
         "zendframework/zend-psr7bridge": "(^0.2) To consume PSR-7 middleware within the MVC workflow",
-        "zendframework/zend-servicemanager-di": "zend-servicemanager-di provides utilities for integrating zend-di and zend-servicemanager in your zend-mvc application"
+        "zendframework/zend-servicemanager-di": "zend-servicemanager-di provides utilities for integrating zend-di and zend-servicemanager in your zend-mvc application",
+        "zendframework/zend-stratigility": "zend-stratigility is required to use middleware pipes in the MiddlewareListener"
     },
     "config": {
         "sort-packages": true

composer.lock

@@ -53,6 +53,13 @@ $route = Literal::factory([
 
 Middleware may be provided as PHP callables, or as service names.
 
+**As of 3.1.0** you may also specify an `array` of middleware, and middleware
+may be [http-interop/http-middleware](https://github.com/http-interop/http-middleware)
+compatible. Each item in the array must be a PHP callable, service name, or
+http-middleware instance. These will then be piped into a
+`Zend\Stratigility\MiddlewarePipe` instance in the order in which they are
+present in the array.
+
 > ### No action required
 > 
 > Unlike action controllers, middleware typically is single purpose, and, as
@@ -69,8 +76,8 @@ 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
+Prior to 3.1.0, 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
@@ -88,14 +95,55 @@ class IndexMiddleware
 }
 ```
 
-From there, you can pull information from the composed request, and manipulate
-the response.
+Starting in 3.1.0, the `MiddlewareListener` always adds middleware to a
+`Zend\Stratigility\MiddlewarePipe` instance, and invokes it as
+[http-interop/http-middleware](https://github.com/http-interop/http-middleware),
+passing it a PSR-7 `ServerRequestInterface` and an http-interop
+`DelegateInterface`. 
+
+As such, ideally your middleware should implement the `MiddlewareInterface` from
+[http-interop/http-middleware](https://github.com/http-interop/http-middleware):
+
+```php
+namespace Application\Middleware;
+
+use Interop\Http\ServerMiddleware\DelegateInterface;
+use Interop\Http\ServerMiddleware\MiddlewareInterface;
+use Psr\Http\Message\ServerRequestInterface;
+
+class IndexMiddleware implements MiddlewareInterface
+{
+    public function process(ServerRequestInterface $request, DelegateInterface $delegate)
+    {
+        // do some work
+    }
+}
+```
+
+Alternately, you may still write `callable` middleware using the following
+signature:
+
+```php
+function (ServerREquestInterface $request, ResponseInterface $response, callable $next)
+{
+    // do some work
+}
+```
+
+In the above case, the `DelegateInterface` is decorated as a callable.
+
+In all versions, within your middleware, you can pull information from the
+composed request, and return a 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..
+> At the time of the 2.7.0 release, route match parameters were not yet injected
+> into the PSR-7 `ServerRequest` instance, and thus not available as request
+> attributes.
+>
+> With the 3.0 release, they are pushed into the PSR-7 `ServerRequest` as
+> attributes, and may thus be fetched using
+> `$request->getAttribute($attributeName)`.
 
 ## Middleware return values
 

doc/book/middleware.md

@@ -12,7 +12,6 @@
 use Interop\Container\ContainerInterface;
 use Zend\EventManager\EventManagerAwareInterface;
 use Zend\EventManager\SharedEventManagerInterface;
-use Zend\Mvc\Exception;
 use Zend\ServiceManager\AbstractPluginManager;
 use Zend\ServiceManager\ConfigInterface;
 use Zend\ServiceManager\Exception\InvalidServiceException;
@@ -46,17 +45,17 @@ class ControllerManager extends AbstractPluginManager
      * event manager and plugin manager.
      *
      * @param  ConfigInterface|ContainerInterface $container
-     * @param  array $v3config
+     * @param  array $config
      */
-    public function __construct($configOrContainerInstance, array $v3config = [])
+    public function __construct($configOrContainerInstance, array $config = [])
     {
         $this->addInitializer([$this, 'injectEventManager']);
         $this->addInitializer([$this, 'injectPluginManager']);
-        parent::__construct($configOrContainerInstance, $v3config);
+        parent::__construct($configOrContainerInstance, $config);
     }
 
     /**
-     * Validate a plugin (v3)
+     * Validate a plugin
      *
      * {@inheritDoc}
      */
@@ -71,26 +70,6 @@ public function validate($plugin)
         }
     }
 
-    /**
-     * Validate a plugin (v2)
-     *
-     * {@inheritDoc}
-     *
-     * @throws Exception\InvalidControllerException
-     */
-    public function validatePlugin($plugin)
-    {
-        try {
-            $this->validate($plugin);
-        } catch (InvalidServiceException $e) {
-            throw new Exception\InvalidControllerException(
-                $e->getMessage(),
-                $e->getCode(),
-                $e
-            );
-        }
-    }
-
     /**
      * Initializer: inject EventManager instance
      *
@@ -101,63 +80,33 @@ public function validatePlugin($plugin)
      * the shared EM injection needs to happen; the conditional will always
      * pass.
      *
-     * @param ContainerInterface|DispatchableInterface $first Container when
-     *     using zend-servicemanager v3; controller under v2.
-     * @param DispatchableInterface|ContainerInterface $second Controller when
-     *     using zend-servicemanager v3; container under v2.
+     * @param ContainerInterface $container
+     * @param DispatchableInterface $controller
      */
-    public function injectEventManager($first, $second)
+    public function injectEventManager(ContainerInterface $container, $controller)
     {
-        if ($first instanceof ContainerInterface) {
-            $container = $first;
-            $controller = $second;
-        } else {
-            $container = $second;
-            $controller = $first;
-        }
-
         if (! $controller instanceof EventManagerAwareInterface) {
             return;
         }
 
         $events = $controller->getEventManager();
         if (! $events || ! $events->getSharedManager() instanceof SharedEventManagerInterface) {
-            // For v2, we need to pull the parent service locator
-            if (! method_exists($container, 'configure')) {
-                $container = $container->getServiceLocator() ?: $container;
-            }
-
             $controller->setEventManager($container->get('EventManager'));
         }
     }
 
     /**
      * Initializer: inject plugin manager
      *
-     * @param ContainerInterface|DispatchableInterface $first Container when
-     *     using zend-servicemanager v3; controller under v2.
-     * @param DispatchableInterface|ContainerInterface $second Controller when
-     *     using zend-servicemanager v3; container under v2.
+     * @param ContainerInterface $container
+     * @param DispatchableInterface $controller
      */
-    public function injectPluginManager($first, $second)
+    public function injectPluginManager(ContainerInterface $container, $controller)
     {
-        if ($first instanceof ContainerInterface) {
-            $container = $first;
-            $controller = $second;
-        } else {
-            $container = $second;
-            $controller = $first;
-        }
-
         if (! method_exists($controller, 'setPluginManager')) {
             return;
         }
 
-        // For v2, we need to pull the parent service locator
-        if (! method_exists($container, 'configure')) {
-            $container = $container->getServiceLocator() ?: $container;
-        }
-
         $controller->setPluginManager($container->get('ControllerPluginManager'));
     }
 }