Merge branch 'feature/request-handler-middleware' into release-3.0.0

Close #150

CHANGELOG.md

@@ -6,6 +6,36 @@ Versions prior to 1.0 were originally released as `phly/conduit`; please visit
 its [CHANGELOG](https://github.com/phly/conduit/blob/master/CHANGELOG.md) for
 details.
 
+## 3.0.0alpha3 - 2018-02-05
+
+### Added
+
+- [#150](https://github.com/zendframework/zend-stratigility/pull/150) adds a new
+  class, `Zend\Stratigility\Middleware\RequestHandlerMiddleware`. The class
+  implements the PSR-15 `RequestHandlerInterface` and `MiddlewareInterface`, and
+  accepts a single constructor argument, a `RequestHandlerInterface` instance.
+  Each of its `handle()` and `process()` methods proxy to the composed request
+  handler's `handle()` method, returning its result.
+
+  This class can be useful for adapting request handlers to use within
+  pipelines.
+
+### Changed
+
+- Nothing.
+
+### Deprecated
+
+- Nothing.
+
+### Removed
+
+- Nothing.
+
+### Fixed
+
+- Nothing.
+
 ## 3.0.0alpha2 - 2018-01-25
 
 ### Added

docs/book/v3/api.md

@@ -228,6 +228,21 @@ $pipeline->pipe(new DoublePassMiddlewareDecorator(
 ));
 ```
 
+### RequestHandlerMiddleware
+
+`Zend\Stratigility\Middleware\RequestHandlerMiddleware` allows you to decorate a
+PSR-15 `RequestHandlerInterface` for use as either a request handler or
+middleware. When either its `handle()` or `process()` method are called, it will
+proxy to the composed request handler's `handle()` method and return the
+response it produces.
+
+This can be useful for piping a final handler to a pipeline.
+
+```php
+// Where $handler is a RequestHandlerInterface:
+$pipeline->pipe(new RequestHandlerMiddleware($handler));
+```
+
 ### ErrorHandler and NotFoundHandler
 
 These two middleware allow you to provide handle PHP errors and exceptions, and

src/Middleware/RequestHandlerMiddleware.php

@@ -0,0 +1,54 @@
+<?php
+/**
+ * @see       https://github.com/zendframework/zend-stratigility for the canonical source repository
+ * @copyright Copyright (c) 2018 Zend Technologies USA Inc. (https://www.zend.com)
+ * @license   https://github.com/zendframework/zend-stratigility/blob/master/LICENSE.md New BSD License
+ */
+declare(strict_types=1);
+
+namespace Zend\Stratigility\Middleware;
+
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Server\MiddlewareInterface;
+use Psr\Http\Server\RequestHandlerInterface;
+
+/**
+ * Decorate a request handler as middleware.
+ *
+ * When pulling handlers from a container, or creating pipelines, it's
+ * simplest if everything is of the same type, so we do not need to worry
+ * about varying execution based on type.
+ *
+ * To manage this, this class decorates request handlers as middleware, so that
+ * they may be piped or routed to. When processed, they delegate handling to the
+ * decorated handler, which will return a response.
+ */
+class RequestHandlerMiddleware implements MiddlewareInterface, RequestHandlerInterface
+{
+    /**
+     * @var RequestHandlerInterface Decorated handler to invoke.
+     */
+    private $handler;
+
+    public function __construct(RequestHandlerInterface $handler)
+    {
+        $this->handler = $handler;
+    }
+
+    /**
+     * Proxies to decorated handler to handle the request.
+     */
+    public function handle(ServerRequestInterface $request) : ResponseInterface
+    {
+        return $this->handler->handle($request);
+    }
+
+    /**
+     * Proxies to decorated handler to handle the request.
+     */
+    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler) : ResponseInterface
+    {
+        return $this->handler->handle($request);
+    }
+}

test/Middleware/RequestHandlerMiddlewareTest.php

@@ -0,0 +1,50 @@
+<?php
+/**
+ * @see       https://github.com/zendframework/zend-stratigility for the canonical source repository
+ * @copyright Copyright (c) 2018 Zend Technologies USA Inc. (https://www.zend.com)
+ * @license   https://github.com/zendframework/zend-stratigility/blob/master/LICENSE.md New BSD License
+ */
+declare(strict_types=1);
+
+namespace ZendTest\Stratigility\Middleware;
+
+use PHPUnit\Framework\TestCase;
+use Prophecy\Argument;
+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 RequestHandlerMiddlewareTest extends TestCase
+{
+    public function setUp()
+    {
+        $this->request = $this->prophesize(ServerRequestInterface::class)->reveal();
+        $this->response = $this->prophesize(ResponseInterface::class)->reveal();
+
+        $this->handler = $this->prophesize(RequestHandlerInterface::class);
+        $this->handler->handle($this->request)->willReturn($this->response);
+
+        $this->middleware = new RequestHandlerMiddleware($this->handler->reveal());
+    }
+
+    public function testDecoratesHandlerAsMiddleware()
+    {
+        $handler = $this->prophesize(RequestHandlerInterface::class);
+        $handler->handle(Argument::any())->shouldNotBeCalled();
+
+        $this->assertSame(
+            $this->response,
+            $this->middleware->process($this->request, $handler->reveal())
+        );
+    }
+
+    public function testDecoratesHandlerAsHandler()
+    {
+        $this->assertSame(
+            $this->response,
+            $this->middleware->handle($this->request)
+        );
+    }
+}