Merge branch 'hotfix/29-middleware-listeners' into release-1.0.0

Forward port #29

Updates `ProblemDetailsMiddlewareTest::testErrorHandlingTriggersListeners` to
mock the http-interop/http-server-handlers `RequestHandlerInterface`
instead of the polyfill interface.

Conflicts:
	CHANGELOG.md

Author: weierophinney

CHANGELOG.md

@@ -37,6 +37,41 @@ Versions 0.3.0 and prior were released as "weierophinney/problem-details".
 
 - Nothing.
 
+## 0.5.2 - 2018-01-10
+
+### Added
+
+- [#29](https://github.com/zendframework/zend-problem-details/pull/29) adds
+  the ability for the `ProblemDetailsMiddleware` to trigger listeners when
+  it catches a `Throwable` to produce a response. Listeners are PHP callables
+  and receive the following arguments, in the following order:
+
+  - `Throwable $error`: the throwable/exception caught by the
+    `ProblemDetailsMiddleware`.
+  - `ServerRequestInterface $request`: the request handled by the
+    `ProblemDetailsMiddleware`.
+  - `ResponseInterface $response`: the response generated by the
+    `ProblemDetailsMiddleware`.
+
+  Attach listeners using the `ProblemDetailsMiddleware::attachListeners()`
+  instance method.
+
+### Changed
+
+- Nothing.
+
+### Deprecated
+
+- Nothing.
+
+### Removed
+
+- Nothing.
+
+### Fixed
+
+- Nothing.
+
 ## 0.5.1 - 2017-12-07
 
 ### Added

docs/book/middleware.md

@@ -53,7 +53,50 @@ This latter approach ensures that you are only providing problem details for
 specific API endpoints, which can be useful when you have a mix of APIs and
 traditional web content in your application.
 
-### Factory
+## Listeners
+
+- Since 0.5.2
+
+The `ProblemDetailsMiddleware` allows you to register _listeners_ to trigger
+when it handles a `Throwable`. Listeners are PHP callables, and the middleware
+triggers them with the following arguments, in the following order:
+
+- `Throwable $error`: the throwable/exception caught by the middleware.
+- `ServerRequestInterface $request`: the request as provided to the
+  `ProblemDetailsMiddleware`.
+- `ResponseInterface $response`: the response the `ProblemDetailsMiddleware`
+  generated based on the `$error`.
+
+Note that each of these arguments are immutable; you cannot change the state in
+a way that that state will propagate meaningfully. As such, you should use
+listeners for reporting purposes only (e.g., logging).
+
+As an example:
+
+```php
+// Where $logger is a PSR-3 logger implementation
+$listener = function (
+    Throwable $error,
+    ServerRequestInterface $request,
+    ResponseInterface $response
+) use ($logger) {
+    $logger->error('[{status}] {method} {uri}: {message}', [
+        'status'  => $response->getStatusCode(),
+        'method'  => $request->getMethod(),
+        'uri'     => (string) $request->getUri(),
+        'message' => $error->getMessage(),
+    ]);
+};
+```
+
+Attach listeners to the `ProblemDetailsMiddleware` instance using its
+`attachListener()` method:
+
+```php
+$middleware->attachListener($listener);
+```
+
+## Factory
 
 The `ProblemDetailsMiddleware` ships with a corresponding PSR-11 compatible factory,
 `ProblemDetailsMiddlewareFactory`. This factory looks for a service named
@@ -63,3 +106,35 @@ to instantiate the middleware.
 For Expressive 2 users, this middleware should be registered automatically with
 your application on install, assuming you have the zend-component-installer
 plugin in place (it's shipped by default with the Expressive skeleton).
+
+### Registering listeners
+
+- Since 0.5.2
+
+In order to register listeners, we recommend using a
+[delegator factory](https://docs.zendframework.com/zend-expressive/features/container/delegator-factories/)
+on the `Zend\ProblemDetails\ProblemDetailsMiddleware` service.
+
+As an example:
+
+```php
+class LoggerProblemDetailsListenerDelegator
+{
+    public function __construct(ContainerInterface $container, $serviceName, callable $callback)
+    {
+        $middleware = $callback();
+        $middleware->attachListener($container->get(LoggerProblemDetailsListener::class));
+        return $middleware;
+    }
+}
+```
+
+You would then register this as a delegator factory in your configuration:
+
+```php
+'delegators' => [
+    ProblemDetailsMiddleware::class => [
+        LoggerProblemDetailsListenerDelegator::class,
+    ],
+],
+```

src/ProblemDetailsMiddleware.php

@@ -23,6 +23,11 @@
  */
 class ProblemDetailsMiddleware implements MiddlewareInterface
 {
+    /**
+     * @var callable[]
+     */
+    private $listeners = [];
+
     /**
      * @var ProblemDetailsResponseFactory
      */
@@ -48,13 +53,38 @@ public function process(ServerRequestInterface $request, RequestHandlerInterface
             $response = $handler->handle($request);
         } catch (Throwable $e) {
             $response = $this->responseFactory->createResponseFromThrowable($request, $e);
+            $this->triggerListeners($e, $request, $response);
         } finally {
             restore_error_handler();
         }
 
         return $response;
     }
 
+    /**
+     * Attach an error listener.
+     *
+     * Each listener receives the following three arguments:
+     *
+     * - Throwable $error
+     * - ServerRequestInterface $request
+     * - ResponseInterface $response
+     *
+     * These instances are all immutable, and the return values of
+     * listeners are ignored; use listeners for reporting purposes
+     * only.
+     *
+     * @param callable $listener
+     */
+    public function attachListener(callable $listener)
+    {
+        if (\in_array($listener, $this->listeners, true)) {
+            return;
+        }
+
+        $this->listeners[] = $listener;
+    }
+
     /**
      * Can the middleware act as an error handler?
      *
@@ -94,4 +124,19 @@ private function createErrorHandler() : callable
             throw new ErrorException($errstr, 0, $errno, $errfile, $errline);
         };
     }
+
+    /**
+     * Trigger all error listeners.
+     *
+     * @param Throwable $error
+     * @param ServerRequestInterface $request
+     * @param ResponseInterface $response
+     * @return void
+     */
+    private function triggerListeners($error, ServerRequestInterface $request, ResponseInterface $response) : void
+    {
+        array_walk($this->listeners, function ($listener) use ($error, $request, $response) {
+            $listener($error, $request, $response);
+        });
+    }
 }

test/ProblemDetailsMiddlewareTest.php

@@ -125,4 +125,37 @@ public function testRethrowsCaughtExceptionIfUnableToNegotiateAcceptHeader() : v
         $this->expectExceptionCode(507);
         $middleware->process($this->request->reveal(), $handler->reveal());
     }
+
+    /**
+     * @dataProvider acceptHeaders
+     */
+    public function testErrorHandlingTriggersListeners(string $accept) : void
+    {
+        $this->request->getHeaderLine('Accept')->willReturn($accept);
+
+        $exception = new TestAsset\RuntimeException('Thrown!', 507);
+
+        $handler = $this->prophesize(RequestHandlerInterface::class);
+        $handler
+            ->handle(Argument::that([$this->request, 'reveal']))
+            ->willThrow($exception);
+
+        $expected = $this->prophesize(ResponseInterface::class)->reveal();
+        $this->responseFactory
+            ->createResponseFromThrowable($this->request->reveal(), $exception)
+            ->willReturn($expected);
+
+        $listener = function ($error, $request, $response) use ($exception, $expected) {
+            $this->assertSame($exception, $error, 'Listener did not receive same exception as was raised');
+            $this->assertSame($this->request->reveal(), $request, 'Listener did not receive same request');
+            $this->assertSame($expected, $response, 'Listener did not receive same response');
+        };
+        $listener2 = clone $listener;
+        $this->middleware->attachListener($listener);
+        $this->middleware->attachListener($listener2);
+
+        $result = $this->middleware->process($this->request->reveal(), $handler->reveal());
+
+        $this->assertSame($expected, $result);
+    }
 }