From 7286f1e4e4014e930f03945abc59031bc4c28d4f Mon Sep 17 00:00:00 2001
From: Matthew Weier O'Phinney <matthew@zend.com>
Date: Tue, 8 Dec 2015 15:39:55 -0600
Subject: [PATCH] Updated url-helper documentation to 1.2.0

This updates the documentation to follow the changes in zend-expressive-helpers
1.2.0 (and upcoming zend-expressive-skeleton 1.0.0rc4). Additionally, it fixes
the header levels of the notes in the server-url-helper documentation.
---
 doc/book/helpers/server-url-helper.md |  2 +-
 doc/book/helpers/url-helper.md        | 62 +++++++++++++++++++++++++--
 2 files changed, 59 insertions(+), 5 deletions(-)

diff --git a/doc/book/helpers/server-url-helper.md b/doc/book/helpers/server-url-helper.md
index 8fb20c00..a0d083c3 100644
--- a/doc/book/helpers/server-url-helper.md
+++ b/doc/book/helpers/server-url-helper.md
@@ -117,7 +117,7 @@ return [
 ]
 ```
 
-> ## Skeleton configures helpers
+> ### Skeleton configures helpers
 >
 > If you started your project using the Expressive skeleton package, the
 > `ServerUrlHelper` and `ServerUrlMiddleware` factories are already registered
diff --git a/doc/book/helpers/url-helper.md b/doc/book/helpers/url-helper.md
index 4510d0dc..2b39416e 100644
--- a/doc/book/helpers/url-helper.md
+++ b/doc/book/helpers/url-helper.md
@@ -57,7 +57,21 @@ Each method will raise an exception if:
 In order to use the helper, you will need to instantiate it with the current
 `RouterInterface`. The factory `Zend\Expressive\Helper\UrlHelperFactory` has
 been provided for this purpose, and can be used trivially with most
-dependency injection containers implementing container-interop:
+dependency injection containers implementing container-interop. Additionally,
+it is most useful when injected with the current results of routing, and as
+such should be registered as a route result observer with the application. The
+following steps should be followed to register and configure the helper:
+
+- Register the `UrlHelper` as a service in your container, using the provided
+  factory.
+- Register the `UrlHelperMiddleware` as a service in your container, using the
+  provided factory.
+- Register the `UrlHelperMiddleware` as pre_routing pipeline middleware.
+
+### Registering the helper service
+
+The following examples demonstrate programmatic registration of the `UrlHelper`
+service in your selected dependency injection container.
 
 ```php
 use Zend\Expressive\Helper\UrlHelper;
@@ -91,15 +105,55 @@ return ['dependencies' => [
 ]]
 ```
 
-> ## Factory requires RouterInterface
+> #### UrlHelperFactory requires RouterInterface
 >
 > The factory requires that a service named `Zend\Expressive\Router\RouterInterface` is present,
 > and will raise an exception if the service is not found.
 
-> ## Skeleton configures helpers
+### Registering the pipeline middleware
+
+To register the `UrlHelperMiddleware` as pre-routing pipeline middleware:
+
+```php
+use Zend\Expressive\Helper\UrlHelperMiddleware;
+
+// Do this early, before piping other middleware or routes:
+$app->pipe(UrlHelperMiddleware::class);
+
+// Or use configuration:
+// [
+//     'middleware_pipeline' => [
+//         'pre_routing' => [
+//             ['middleware' => UrlHelperMiddleware::class],
+//         ],
+//     ],
+// ]
+```
+
+The following dependency configuration will work for all three when using the
+Expressive skeleton:
+
+```php
+return [
+    'dependencies' => [
+        'factories' => [
+            UrlHelper::class => UrlHelperFactory::class,
+            UrlHelperMiddleware::class => UrlHelperMiddlewareFactory::class,
+        ],
+    ],
+    'middleware_pipeline' => [
+        'pre_routing' => [
+            ['middleware' => UrlHelperMiddleware::class],
+        ],
+    ],
+]
+```
+
+> #### Skeleton configures helpers
 >
 > If you started your project using the Expressive skeleton package, the
-> `UrlHelper` factory is already registered for you.
+> `UrlHelper` and `UrlHelperMiddleware` factories are already registered for
+> you, as is the `UrlHelperMiddleware` pre_routing pipeline middleware.
 
 ## Using the helper in middleware