Merge branch 'feature/456' into develop

Close #460
Close #456

Finishes out Expressive 2.0 documentation tasks

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

doc/book/features/helpers/url-helper.md

@@ -64,6 +64,12 @@ Each method will raise an exception if:
   represents a matching failure.
 - The given `$routeName` is not defined in the router.
 
+> ### Signature changes
+>
+> The signature listed above is current as of version 3.0.0 of
+> zendframework/zend-expressive-helpers. Prior to that version, the helper only
+> accepted the route name and route parameters.
+
 ## Creating an instance
 
 In order to use the helper, you will need to instantiate it with the current

doc/book/features/router/interface.md

@@ -76,6 +76,21 @@ Implementors should also read the following sections detailing the `Route` and
 `RouteResult` classes, to ensure that their implementations interoperate
 correctly.
 
+> ### generateUri() signature change in 2.0
+>
+> Prior to zendframework/zend-expressive-router 2.0.0, the signature of
+> `generateUri()` was:
+>
+> ```php
+> public function generateUri(
+>     string $name,
+>     array $substitutions = []
+> ) : string
+> ```
+> 
+> If you are targeting that version, you may still provide the `$options`
+> argument, but it will not be invoked.
+
 ## Routes
 
 Routes are defined via `Zend\Expressive\Router\Route`, and aggregate the

doc/book/features/template/twig.md

@@ -127,3 +127,8 @@ return [
     ],
 ];
 ```
+
+When specifying the `twig.extensions` values, always use fully qualified class
+names or actual extension instances to ensure compatibility with any version of
+Twig used. Version 2 of Twig _requires_ that a fully qualified class name is
+used, and not a short-name alias.

doc/book/features/template/zend-view.md

@@ -92,6 +92,10 @@ for doing so:
 In each case, the zend-view implementation will do a depth-first, recursive
 render in order to provide content within the selected layout.
 
+- Since 1.3: You may also pass a boolean `false` value to either
+  `addDefaultParam()` or via the template variables for the `layout` key; doing
+  so will disable the layout.
+
 ### Layout name passed to constructor
 
 ```php