Documents ProblemDetailsMiddleware listeners

Documents new features provided by #29.

Author: weierophinney

docs/book/middleware.md

@@ -55,7 +55,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
@@ -65,3 +108,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,
+    ],
+],
+```