Demonstrate using keys for middleware specs

By using keys, you can have multiple configurations that are related, and which
will merge into a single pipeline.

This also allows us to have a common "routing" key for the routing middleware,
which makes it easier to identify and replace if desired.

Author: weierophinney

doc/book/container/factories.md

@@ -35,7 +35,7 @@ instance.
 When the `config` service is present, the factory can utilize several keys in
 order to seed the `Application` instance:
 
-- `middleware_pipeline` can be used to seed pre- and/or post-routing middleware:
+- `middleware_pipeline` can be used to seed the middleware pipeline:
 
   ```php
   'middleware_pipeline' => [
@@ -75,6 +75,10 @@ order to seed the `Application` instance:
   granular priority values to specify the order in which middleware should be
   piped to the application.
 
+  You *can* specify keys for each middleware specification. These will be
+  ignored by the factory, but can be useful when merging several configurations
+  into one for the application.
+
 - `routes` is used to define routed middleware. The value must be an array,
   consisting of arrays defining each middleware:
 

doc/book/cookbook/custom-404-page-handling.md

@@ -92,7 +92,14 @@ configuration, after the dispatch middleware:
 ```php
 'middleware_pipeline' => [
     /* ... */
-    Zend\Expressive\Container\ApplicationFactory::DISPATCH_MIDDLEWARE,
+    'routing' => [
+        'middleware' => [
+            Zend\Expressive\Container\ApplicationFactory::ROUTING_MIDDLEWARE,
+            Zend\Expressive\Helper\UrlHelperMiddleware::class,
+            Zend\Expressive\Container\ApplicationFactory::DISPATCH_MIDDLEWARE,
+        ],
+        'priority' => 1,
+    ],
     [
         'middleware' => 'Application\NotFound',
         'priority' => -1,

doc/book/cookbook/route-specific-pipeline.md

@@ -168,7 +168,7 @@ answer is that the syntax is exactly the same!
 ```php
 return [
     'middleware_pipeline' => [
-        [
+        'api' => [
             'path' => '/api',
             'middleware' => [
                 'AuthenticationMiddleware',

doc/book/cookbook/setting-locale-depending-routing-parameter.md

@@ -142,6 +142,7 @@ return [
         [
             'middleware' => [
                 Zend\Expressive\Container\ApplicationFactory::ROUTING_MIDDLEWARE,
+                Helper\UrlHelperMiddleware::class,
                 [ 'middleware' => LocalizationMiddleware::class ],
                 Zend\Expressive\Container\ApplicationFactory::DISPATCH_MIDDLEWARE,
             ],

doc/book/cookbook/setting-locale-without-routing-parameter.md

@@ -112,12 +112,11 @@ return [
 
         /* ... */
 
-        [
+        'routing' => [
             'middleware' => [
                 Zend\Expressive\Container\ApplicationFactory::ROUTING_MIDDLEWARE,
                 Zend\Expressive\Helper\UrlHelperMiddleware::class,
                 Zend\Expressive\Container\ApplicationFactory::DISPATCH_MIDDLEWARE,
-                /* ... */
             ],
             'priority' => 1,
         ],

doc/book/cookbook/using-a-base-path.md

@@ -108,7 +108,14 @@ return [
     'middleware_pipeline' => [
         [ 'middleware' => [ Blast\BaseUrl\BaseUrlMiddleware::class ], 'priority' => 1000 ],
         /* ... */
-        Zend\Expressive\Container\ApplicationFactory::ROUTING_MIDDLEWARE,
+        'routing' => [
+            'middleware' => [
+                Zend\Expressive\Container\ApplicationFactory::ROUTING_MIDDLEWARE,
+                Zend\Expressive\Helper\UrlHelperMiddleware::class,
+                Zend\Expressive\Container\ApplicationFactory::DISPATCH_MIDDLEWARE,
+            ],
+            'priority' => 1,
+        ],
         /* ... */
     ],
 ];

doc/book/cookbook/using-zend-form-view-helpers.md

@@ -226,7 +226,14 @@ return [
     'middleware_pipeline' => [
         ['middleware' => Your\Application\FormHelpersMiddleware::class, 'priority' => 1000],
         /* ... */
-        Zend\Expressive\Container\ApplicationFactory::ROUTING_MIDDLEWARE,
+        'routing' => [
+            'middleware' => [
+                Zend\Expressive\Container\ApplicationFactory::ROUTING_MIDDLEWARE,
+                Zend\Expressive\Helper\UrlHelperMiddleware::class,
+                Zend\Expressive\Container\ApplicationFactory::DISPATCH_MIDDLEWARE,
+            ],
+            'priority' => 1,
+        ],
         /* ... */
     ],
 ];

doc/book/helpers/body-parse.md

@@ -45,7 +45,14 @@ return [
     'middleware_pipeline' => [
         [ 'middleware' => Helper\BodyParams\BodyParamsMiddleware::class, 'priority' => 100],
         /* ... */
-        Zend\Expressive\Container\ApplicationFactory::ROUTING_MIDDLEWARE,
+        'routing' => [
+            'middleware' => [
+                Zend\Expressive\Container\ApplicationFactory::ROUTING_MIDDLEWARE,
+                Helper\UrlHelperMiddleware::class,
+                Zend\Expressive\Container\ApplicationFactory::DISPATCH_MIDDLEWARE,
+            ],
+            'priority' => 1,
+        ],
         /* ... */
     ],
 ];

doc/book/helpers/url-helper.md

@@ -140,7 +140,7 @@ $app->pipeDispatchMiddleware();
 // [
 //     'middleware_pipeline' => [
 //         /* ... */
-//         [
+//         'routing' => [
 //             'middleware' => [
 //                 Zend\Expressive\Container\ApplicationFactory::ROUTING_MIDDLEWARE,
 //                 UrlHelperMiddleware::class
@@ -181,7 +181,7 @@ return [
         ],
     ],
     'middleware_pipeline' => [
-        [
+        'routing' => [
             'middleware' => [
                 Zend\Expressive\Container\ApplicationFactory::ROUTING_MIDDLEWARE,
                 UrlHelperMiddleware::class,

doc/book/migration/rc-to-v1.md

@@ -298,20 +298,20 @@ This would be rewritten to the following to work with RC6 and later:
 ```php
 return [
     'middleware_pipeline' => [
-        [
+        'always' => [
             'middleware' => [
                 Zend\Expressive\Helper\ServerUrlMiddleware::class,
                 DebugToolbarMiddleware::class,
             ],
             'priority' => PHP_INT_MAX,
         ],
-        [
+        'api' => [
             'middleware' => ApiMiddleware::class,
             'path' => '/api,
             'priority' => 100,
         ],
 
-        [
+        'routing' => [
             'middleware' => [
                 Zend\Expressive\Container\ApplicationFactory::ROUTING_MIDDLEWARE,
                 Zend\Expressive\Helper\UrlHelperMiddleware::class,
@@ -320,7 +320,7 @@ return [
             'priority' => 1,
         ],
 
-        [
+        'error' => [
             'middleware' => [
                 NotFoundMiddleware::class,
             ],
@@ -336,6 +336,16 @@ priority, you can simplify adding new middleware, particularly if you know it
 should execute before routing, or as error middleware, or between routing and
 dispatch.
 
+> #### Keys are ignored
+>
+> The above example provides keys for each middleware specification. The factory
+> will ignore these, but they can be useful for cases when you might want to
+> specify configuration in multiple files, and merge specific entries together.
+> Be aware, however, that the `middleware` key itself is an indexed array;
+> items will be appended based on the order in which configuration files are
+> merged. If order of these is important, create separate specifications with
+> relevant `priority` values.
+
 ## Route result observer deprecation
 
 As of RC6, the following changes have occurred with regards to route result
@@ -378,7 +388,7 @@ however, you will need to register it following the routing middleware:
 [
     'middleware_pipeline' => [
         /* ... */
-        [
+        'routing' => [
             'middleware' => [
                 Zend\Expressive\Container\ApplicationFactory::ROUTING_MIDDLEWARE,
                 Zend\Expressive\Container\ApplicationFactory::ROUTE_RESULT_OBSERVER_MIDDLEWARE,
@@ -460,7 +470,7 @@ If you are using the `ApplicationFactory`, alter your configuration:
 [
     'middleware_pipeline' => [
         /* ... */
-        [
+        'routing' => [
             'middleware' => [
                 Zend\Expressive\Container\ApplicationFactory::ROUTING_MIDDLEWARE,
                 ['middleware' => MyObserver::class],