Allow using PSR-15 request handlers

This patch updates the `MiddlewareContainer` and `MiddlewareFactory` to
allow them to detect PSR-15 request handlers, and decorate them using
zend-stratigility's `RequestHandlerMiddleware`. This ensures type-safety
when used in either pipelines or with routed middleware, but also
ensures we can use the full-spectrum of available handlers with the
system.

A new method was also added to `MiddlewareFactory`: `handler()`. This
method accepts a `RequestHandlerInterface` instance and returns a
`RequestHandlerMiddleware` instance decorating it, making it simple to
use request handlers with the explicit functionality of
zend-expressive-router's `PathBasedRoutingMiddleware` API.

Author: weierophinney

composer.json

@@ -31,7 +31,7 @@
         "zendframework/zend-expressive-router": "^3.0.0alpha1",
         "zendframework/zend-expressive-template": "^2.0.0-dev",
         "zendframework/zend-httphandlerrunner": "^1.0",
-        "zendframework/zend-stratigility": "^3.0.0alpha2"
+        "zendframework/zend-stratigility": "3.0.0alpha3"
     },
     "require-dev": {
         "filp/whoops": "^1.1.10 || ^2.1.13",

composer.lock

@@ -92,11 +92,12 @@ public function run() : void
      *
      * The resulting middleware, in both cases, is piped to the pipeline.
      *
-     * @param string|array|callable|MiddlewareInterface $middlewareOrPath
+     * @param string|array|callable|MiddlewareInterface|RequestHandlerInterface $middlewareOrPath
      *     Either the middleware to pipe, or the path to segregate the $middleware
      *     by, via a PathMiddlewareDecorator.
-     * @param null|string|array|callable|MiddlewareInterface $middleware If present,
-     *     middleware to segregate by the path specified in $middlewareOrPath.
+     * @param null|string|array|callable|MiddlewareInterface|RequestHandlerInterface $middleware
+     *     If present, middleware or request handler to segregate by the path
+     *     specified in $middlewareOrPath.
      */
     public function pipe($middlewareOrPath, $middleware = null) : void
     {
@@ -113,8 +114,9 @@ public function pipe($middlewareOrPath, $middleware = null) : void
     /**
      * Add a route for the route middleware to match.
      *
-     * @param string|array|callable|MiddlewareInterface $middleware Middleware
-     *     (or middleware service name) to associate with route.
+     * @param string|array|callable|MiddlewareInterface|RequestHandlerInterface $middleware
+     *     Middleware or request handler (or service name resolving to one of
+     *     those types) to associate with route.
      * @param null|array $methods HTTP method to accept; null indicates any.
      * @param null|string $name The name of the route.
      */
@@ -129,8 +131,9 @@ public function route(string $path, $middleware, array $methods = null, string $
     }
 
     /**
-     * @param string|array|callable|MiddlewareInterface $middleware Middleware
-     *     (or middleware service name) to associate with route.
+     * @param string|array|callable|MiddlewareInterface|RequestHandlerInterface $middleware
+     *     Middleware or request handler (or service name resolving to one of
+     *     those types) to associate with route.
      * @param null|string $name The name of the route.
      */
     public function get(string $path, $middleware, string $name = null) : Router\Route
@@ -139,8 +142,9 @@ public function get(string $path, $middleware, string $name = null) : Router\Rou
     }
 
     /**
-     * @param string|array|callable|MiddlewareInterface $middleware Middleware
-     *     (or middleware service name) to associate with route.
+     * @param string|array|callable|MiddlewareInterface|RequestHandlerInterface $middleware
+     *     Middleware or request handler (or service name resolving to one of
+     *     those types) to associate with route.
      * @param null|string $name The name of the route.
      */
     public function post(string $path, $middleware, $name = null) : Router\Route
@@ -149,8 +153,9 @@ public function post(string $path, $middleware, $name = null) : Router\Route
     }
 
     /**
-     * @param string|array|callable|MiddlewareInterface $middleware Middleware
-     *     (or middleware service name) to associate with route.
+     * @param string|array|callable|MiddlewareInterface|RequestHandlerInterface $middleware
+     *     Middleware or request handler (or service name resolving to one of
+     *     those types) to associate with route.
      * @param null|string $name The name of the route.
      */
     public function put(string $path, $middleware, string $name = null) : Router\Route
@@ -159,8 +164,9 @@ public function put(string $path, $middleware, string $name = null) : Router\Rou
     }
 
     /**
-     * @param string|array|callable|MiddlewareInterface $middleware Middleware
-     *     (or middleware service name) to associate with route.
+     * @param string|array|callable|MiddlewareInterface|RequestHandlerInterface $middleware
+     *     Middleware or request handler (or service name resolving to one of
+     *     those types) to associate with route.
      * @param null|string $name The name of the route.
      */
     public function patch(string $path, $middleware, string $name = null) : Router\Route
@@ -169,8 +175,9 @@ public function patch(string $path, $middleware, string $name = null) : Router\R
     }
 
     /**
-     * @param string|array|callable|MiddlewareInterface $middleware Middleware
-     *     (or middleware service name) to associate with route.
+     * @param string|array|callable|MiddlewareInterface|RequestHandlerInterface $middleware
+     *     Middleware or request handler (or service name resolving to one of
+     *     those types) to associate with route.
      * @param null|string $name The name of the route.
      */
     public function delete(string $path, $middleware, string $name = null) : Router\Route
@@ -179,8 +186,9 @@ public function delete(string $path, $middleware, string $name = null) : Router\
     }
 
     /**
-     * @param string|array|callable|MiddlewareInterface $middleware Middleware
-     *     (or middleware service name) to associate with route.
+     * @param string|array|callable|MiddlewareInterface|RequestHandlerInterface $middleware
+     *     Middleware or request handler (or service name resolving to one of
+     *     those types) to associate with route.
      * @param null|string $name The name of the route.
      */
     public function any(string $path, $middleware, string $name = null) : Router\Route

src/Application.php

@@ -10,6 +10,7 @@
 namespace Zend\Expressive\Exception;
 
 use Psr\Http\Server\MiddlewareInterface;
+use Psr\Http\Server\RequestHandlerInterface;
 use RuntimeException;
 
 class InvalidMiddlewareException extends RuntimeException implements ExceptionInterface
@@ -22,9 +23,10 @@ public static function forMiddleware($middleware) : self
     {
         return new self(sprintf(
             'Middleware "%s" is neither a string service name, a PHP callable,'
-            . ' a %s instance, or an array of such arguments',
+            . ' a %s instance, a %s instance, or an array of such arguments',
             is_object($middleware) ? get_class($middleware) : gettype($middleware),
-            MiddlewareInterface::class
+            MiddlewareInterface::class,
+            RequestHandlerInterface::class
         ));
     }
 

src/Exception/InvalidMiddlewareException.php

@@ -10,7 +10,11 @@
 namespace Zend\Expressive;
 
 use Psr\Container\ContainerInterface;
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
 use Psr\Http\Server\MiddlewareInterface;
+use Psr\Http\Server\RequestHandlerInterface;
+use Zend\Stratigility\Middleware\RequestHandlerMiddleware;
 
 class MiddlewareContainer implements ContainerInterface
 {
@@ -55,6 +59,10 @@ public function get($service) : MiddlewareInterface
             ? $this->container->get($service)
             : new $service();
 
+        $middleware = $middleware instanceof RequestHandlerInterface
+            ? new RequestHandlerMiddleware($middleware)
+            : $middleware;
+
         if (! $middleware instanceof MiddlewareInterface) {
             throw Exception\InvalidMiddlewareException::forMiddlewareService($service, $middleware);
         }

src/MiddlewareContainer.php

@@ -11,8 +11,10 @@
 
 use Psr\Container\ContainerInterface;
 use Psr\Http\Server\MiddlewareInterface;
+use Psr\Http\Server\RequestHandlerInterface;
 use Zend\Stratigility\MiddlewarePipe;
 use Zend\Stratigility\Middleware\CallableMiddlewareDecorator;
+use Zend\Stratigility\Middleware\RequestHandlerMiddleware;
 
 /**
  * Marshal middleware for use in the application.
@@ -23,17 +25,20 @@
  * If any middleware provided is already a MiddlewareInterface, it can be used
  * verbatim or decorated as-is. Other middleware types acceptable are:
  *
+ * - PSR-15 RequestHandlerInterface instances; these will be decorated as
+ *   RequestHandlerMiddleware instances.
  * - string service names resolving to middleware
  * - arrays of service names and/or MiddlewareInterface instances
  * - PHP callables that follow the PSR-15 signature
  *
- * Additionally, the class provides several decorator/utility methods:
+ * Additionally, the class provides the following decorator/utility methods:
  *
  * - callable() will decorate the callable middleware passed to it using
  *   CallableMiddlewareDecorator.
- * - path() will decorate the path and middleware passed to it using
- *   PathMiddlewareDecorator, after first passing the middleware to the prepare()
- *   method.
+ * - handler() will decorate the request handler passed to it using
+ *   RequestHandlerMiddleware.
+ * - lazy() will decorate the string service name passed to it, along with the
+ *   factory instance, as a LazyLoadingMiddleware instance.
  * - pipeline() will create a MiddlewarePipe instance from the array of
  *   middleware passed to it, after passing each first to prepare().
  */
@@ -50,7 +55,7 @@ public function __construct(MiddlewareContainer $container)
     }
 
     /**
-     * @param string|array|callable|MiddlewareInterface $middleware
+     * @param string|array|callable|MiddlewareInterface|RequestHandlerInterface $middleware
      * @throws Exception\InvalidMiddlewareException if argument is not one of
      *    the specified types.
      */
@@ -60,6 +65,10 @@ public function prepare($middleware) : MiddlewareInterface
             return $middleware;
         }
 
+        if ($middleware instanceof RequestHandlerInterface) {
+            return new RequestHandlerMiddleware($middleware);
+        }
+
         if (is_callable($middleware)) {
             return $this->callable($middleware);
         }
@@ -83,6 +92,14 @@ public function callable(callable $middleware) : CallableMiddlewareDecorator
         return new CallableMiddlewareDecorator($middleware);
     }
 
+    /**
+     * Decorate a RequestHandlerInterface as middleware via RequestHandlerMiddleware.
+     */
+    public function handler(RequestHandlerInterface $handler) : RequestHandlerMiddleware
+    {
+        return new RequestHandlerMiddleware($handler);
+    }
+
     /**
      * Create lazy loading middleware based on a service name.
      */

src/MiddlewareFactory.php

@@ -10,11 +10,14 @@
 namespace ZendTest\Expressive;
 
 use PHPUnit\Framework\TestCase;
+use Prophecy\Argument;
 use Psr\Container\ContainerInterface;
 use Psr\Http\Server\MiddlewareInterface;
+use Psr\Http\Server\RequestHandlerInterface;
 use Zend\Expressive\Exception;
 use Zend\Expressive\MiddlewareContainer;
 use Zend\Expressive\Router\DispatchMiddleware;
+use Zend\Stratigility\Middleware\RequestHandlerMiddleware;
 
 class MiddlewareContainerTest extends TestCase
 {
@@ -85,4 +88,18 @@ public function testGetReturnsInstantiatedClass()
         $middleware = $this->container->get(DispatchMiddleware::class);
         $this->assertInstanceOf(DispatchMiddleware::class, $middleware);
     }
+
+    public function testGetWillDecorateARequestHandlerAsMiddleware()
+    {
+        $handler = $this->prophesize(RequestHandlerInterface::class)->reveal();
+
+        $this->originContainer->has('AHandlerNotMiddleware')->willReturn(true);
+        $this->originContainer->get('AHandlerNotMiddleware')->willReturn($handler);
+
+        $middleware = $this->container->get('AHandlerNotMiddleware');
+
+        // Test that we get back middleware decorating the handler
+        $this->assertInstanceOf(RequestHandlerMiddleware::class, $middleware);
+        $this->assertAttributeSame($handler, 'handler', $middleware);
+    }
 }

test/MiddlewareContainerTest.php

@@ -11,6 +11,7 @@
 
 use PHPUnit\Framework\TestCase;
 use Psr\Http\Server\MiddlewareInterface;
+use Psr\Http\Server\RequestHandlerInterface;
 use ReflectionProperty;
 use Zend\Expressive\Exception;
 use Zend\Expressive\MiddlewareContainer;
@@ -19,6 +20,7 @@
 use Zend\Expressive\Router\DispatchMiddleware;
 use Zend\Stratigility\MiddlewarePipe;
 use Zend\Stratigility\Middleware\CallableMiddlewareDecorator;
+use Zend\Stratigility\Middleware\RequestHandlerMiddleware;
 
 class MiddlewareFactoryTest extends TestCase
 {
@@ -194,4 +196,20 @@ public function testPipelineAllowsPipingArraysOfMiddlewareAndCastsThemToInternal
         $this->assertCallableMiddleware($callable, $received[0]);
         $this->assertSame($middleware, $received[1]);
     }
+
+    public function testPrepareDecoratesRequestHandlersAsMiddleware()
+    {
+        $handler = $this->prophesize(RequestHandlerInterface::class)->reveal();
+        $middleware = $this->factory->prepare($handler);
+        $this->assertInstanceOf(RequestHandlerMiddleware::class, $middleware);
+        $this->assertAttributeSame($handler, 'handler', $middleware);
+    }
+
+    public function testHandlerDecoratesRequestHandlersAsMiddleware()
+    {
+        $handler = $this->prophesize(RequestHandlerInterface::class)->reveal();
+        $middleware = $this->factory->handler($handler);
+        $this->assertInstanceOf(RequestHandlerMiddleware::class, $middleware);
+        $this->assertAttributeSame($handler, 'handler', $middleware);
+    }
 }