Documented listening for errors

- Added a section in the error handling documentation for "listening for
  errors".
- The documentation kind of requires knowledge of delegator factories,
  so added a chapter on delegator factories as well.

Author: weierophinney

doc/book/features/container/delegator-factories.md

@@ -0,0 +1,65 @@
+# Delegator Factories
+
+- Since 2.0.
+
+Starting with the 2.0 version of the Expressive skeleton, we now support the
+concept of _delegator factories_, which allow decoration of services created by
+your dependency injection container, across all dependency injection containers
+supported by Expressive.
+
+_Delegator factories_ accept the following arguments:
+
+- The container itself;
+- The name of the service whose creation is being decrorated;
+- A callback that will produce the service being decorated.
+
+As an example, let's say we have a `UserRepository` class that composes some sort of
+event manager. We might want to attach listeners to that event manager, but not
+wish to alter the basic creation logic for the repository itself. As such, we
+might write a _delegator factory_ as follows:
+
+```php
+namespace Acme;
+
+use Psr\Container\ContainerInterface;
+use Psr\Log\LoggerInterface;
+
+class UserRepositoryListenerDelegatorFactory
+{
+    /**
+     * @param ContainerInterface $container
+     * @param string $name
+     * @param callable $callback
+     * @return UserRepository
+     */
+    public function __invoke(ContainerInterface $container, $name, callable $callback)
+    {
+        $listener = new LoggerListener($container->get(LoggerInterface::class));
+        $repository = $callback();
+        $repository->getEventManager()->attach($listener);
+        return $repository;
+    }
+}
+```
+
+To notify the container about this delegator factory, we would add the following
+configuration to our application:
+
+```php
+'dependencies' => [
+    'delegators' => [
+        Acme\UserRepository::class => [
+            Acme\UserRepositoryListenerDelegatorFactory::class,
+        ],
+    ],
+],
+```
+
+Note that you specify delegator factories using the service name being decorated
+as the key, with an _array_ of delegator factories as a value. **You may attach
+multiple delegator factories to any given service**, which can be a very
+powerful feature.
+
+At the time of writing, this feature works for each of the Aura.Di, Pimple, and
+zend-servicemanager container implementations. Delegator factories have been
+supported with Pimple and zend-servicemanager since the 1.X series.

doc/book/features/error-handling.md

@@ -137,6 +137,93 @@ return [
 > `config/autoload/*.local.php` file with the above configuration whenever you
 > want to enable whoops.
 
+## Listening for errors
+
+When errors occur, you may want to _listen_ for them in order to provide
+features such as logging. `Zend\Stratigility\Middleware\ErrorHandler` provides
+the ability to do so via its `attachListener()` method.
+
+This method accepts a callable with the following signature:
+
+```php
+function (
+    Throwable|Exception $error,
+    ServerRequestInterface $request,
+    ResponseInterface $response
+) : void
+```
+
+The response provided is the response returned by your error response generator,
+allowing the listener the ability to introspect the generated response as well.
+
+As an example, you could create a logging listener as follows:
+
+```php
+namespace Acme;
+
+use Exception;
+use Psr\Log\LoggerInterface;
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use Throwable;
+
+class LoggingErrorListener
+{
+    /**
+     * Log format for messages:
+     *
+     * STATUS [METHOD] path: message
+     */
+    const LOG_FORMAT = '%d [%s] %s: %s';
+
+    private $logger;
+
+    public function __construct(LoggerInterface $logger)
+    {
+        $this->logger = $logger;
+    }
+
+    public function __invoke($error, ServerRequestInterface $request, ResponseInterface $response)
+    {
+        $this->logger->error(sprintf(
+            self::LOG_FORMAT,
+            $response->getStatusCode(),
+            $request->getMethod(),
+            (string) $request->getUri(),
+            $error->getMessage()
+        ));
+    }
+}
+```
+
+You could then use a [delegator factory](container/delegator-factories.md) to
+create your logger listener and attach it to your error handler:
+
+```php
+namespace Acme;
+
+use Psr\Container\ContainerInterface;
+use Psr\Log\LoggerInterface;
+use Zend\Stratigility\Middleware\ErrorHandler;
+
+class LoggerErrorListenerDelegatorFactory
+{
+    /**
+     * @param ContainerInterface $container
+     * @param string $name
+     * @param callable $callback
+     * @return ErrorHandler
+     */
+    public function __invoke(ContainerInterface $container, $name, callable $callback)
+    {
+        $listener = new LoggerErrorListener($container->get(LoggerInterface::class));
+        $errorHandler = $callback();
+        $errorHandler->attachListener($listener);
+        return $errorHandler;
+    }
+}
+```
+
 ## Handling more specific error types
 
 You could also write more specific error handlers. As an example, you might want

mkdocs.yml

@@ -12,6 +12,7 @@ pages:
         - Containers:
             - Introduction: features/container/intro.md
             - 'Container Factories': features/container/factories.md
+            - 'Delegator Factories': features/container/delegator-factories.md
             - 'Using zend-servicemanager': features/container/zend-servicemanager.md
             - 'Using Pimple': features/container/pimple.md
             - 'Using Aura.Di': features/container/aura-di.md