Merge branch 'hotfix/pipeline-config'

Close #270

Author: weierophinney

CHANGELOG.md

@@ -2,9 +2,32 @@
 
 All notable changes to this project will be documented in this file, in reverse chronological order by release.
 
-## 1.0.0 - TBD
-
-First stable release.
+## 1.0.0rc6 - TBD
+
+Sixth release candidate.
+
+This release contains backwards compatibility breaks with previous release
+candidates. All previous functionality should continue to work, but will
+emit `E_USER_DEPRECATED` notices prompting you to update your application.
+In particular:
+
+- The routing middleware has been split into two separate middleware
+  implementations, one for routing, another for dispatching. This eliminates the
+  need for the route result observer system, as middleware can now be placed
+  *between* routing and dispatching — an approach that provides for greater
+  flexibility with regards to providing route-based functionality.
+- As a result of the above, `Zend\Expressive\Application` no longer implements
+  `Zend\Expressive\Router\RouteResultSubjectInterface`, though it retains the
+  methods associated (each emits a deprecation notice).
+- Configuration for `Zend\Expressive\Container\ApplicationFactory` was modified
+  to implement the `middleware_pipeline` as a single queue, instead of
+  segregating it between `pre_routing` and `post_routing`. Each item in the
+  queue follows the original middleware specification from those keys, with one
+  addition: a `priority` key can be used to allow you to granularly shape the
+  execution order of the middleware pipeline.
+
+A [migration guide](http://zend-expressive.rtfd.org/en/latest/migration/rc-to-v1/)
+was written to help developers migrate to RC6 from earlier versions.
 
 ### Added
 
@@ -24,14 +47,44 @@ First stable release.
   a flow/architectural diagram to the "features" chapter.
 - [#262](https://github.com/zendframework/zend-expressive/pull/262) adds
   a recipe demonstrating creating classes that can intercept multiple routes.
+- [#270](https://github.com/zendframework/zend-expressive/pull/270) adds
+  new methods to `Zend\Expressive\Application`:
+  - `dispatchMiddleware()` is new middleware for dispatching the middleware
+    matched by routing (this functionality was split from `routeMiddleware()`).
+  - `routeResultObserverMiddleware()` is new middleware for notifying route
+    result observers, and exists only to aid migration functionality; it is
+    marked deprecated!
+  - `pipeDispatchMiddleware()` will pipe the dispatch middleware to the
+    `Application` instance.
+  - `pipeRouteResultObserverMiddleware()` will pipe the route result observer
+    middleware to the `Application` instance; like
+    `routeResultObserverMiddleware()`, the method only exists for aiding
+    migration, and is marked deprecated.
+- [#270](https://github.com/zendframework/zend-expressive/pull/270) adds
+  `Zend\Expressive\MarshalMiddlewareTrait`, which is composed by
+  `Zend\Expressive\Application`; it provides methods for marshaling
+  middleware based on service names or arrays of services.
 
 ### Deprecated
 
-- Nothing.
+- [#270](https://github.com/zendframework/zend-expressive/pull/270) deprecates
+  the following methods in `Zend\Expressive\Application`, all of which will
+  be removed in version 1.1:
+  - `attachRouteResultObserver()`
+  - `detachRouteResultObserver()`
+  - `notifyRouteResultObservers()`
+  - `pipeRouteResultObserverMiddleware()`
+  - `routeResultObserverMiddleware()`
 
 ### Removed
 
-- Nothing.
+- [#270](https://github.com/zendframework/zend-expressive/pull/270) removes the
+  `Zend\Expressive\Router\RouteResultSubjectInterface` implementation from
+  `Zend\Expressive\Application`.
+- [#270](https://github.com/zendframework/zend-expressive/pull/270) eliminates
+  the `pre_routing`/`post_routing` terminology from the `middleware_pipeline`,
+  in favor of individually specified `priority` values in middleware
+  specifications.
 
 ### Fixed
 

doc/book/application.md

@@ -186,21 +186,24 @@ function ($error, ServerRequestInterface $request, ResponseInterface $response,
 
 Read the section on [piping vs routing](router/piping.md) for more information.
 
-### Registering routing middleware
+### Registering routing and dispatch middleware
 
-Routing is accomplished via dedicated a dedicated middleware method, 
-`Application::routeMiddleware()`. It is an instance method, and can be
-piped/registered with other middleware platforms if desired.
+Routing is accomplished via a dedicated middleware method,
+`Application::routeMiddleware()`; similarly, dispatching of routed middleware
+has a corresponding instance middleware method, `Application::dispatchMiddleware()`.
+Each can be piped/registered with other middleware platforms if desired.
 
-Internally, the first time `route()` is called (including via one of the proxy
-methods), or, if never called, when `__invoke()` (the exposed application
-middleware) is called, the instance will pipe `Application::routeMiddleware` to
-the middleware pipeline. You can also pipe it manually if desired:
+These methods **MUST** be piped to the application so that the application will
+route and dispatch routed middleware. This is done using the following methods:
 
 ```php
 $app->pipeRoutingMiddleware();
+$app->pipeDispatchMiddleware();
 ```
 
+See the section on [piping](router/piping.md) to see how you can register
+non-routed middleware and create layered middleware applications.
+
 ## Retrieving dependencies
 
 As noted in the intro, the `Application` class has several dependencies. Some of

doc/book/container/factories.md

@@ -35,22 +35,20 @@ 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' => [
-      // An array of middleware to register prior to registration of the
-      // routing middleware:
-      'pre_routing' => [
-      ],
-      // An array of middleware to register after registration of the
-      // routing middleware:
-      'post_routing' => [
-      ],
+      // An array of middleware to register.
+      [ /* ... */ ],
+      Zend\Expressive\Container\ApplicationFactory::ROUTING_MIDDLEWARE,
+      Zend\Expressive\Container\ApplicationFactory::DISPATCH_MIDDLEWARE,
+      [ /* ... */ ],
   ],
   ```
 
-  Each item of each array must be an array itself, with the following structure:
+  Each item of the array, other than the entries for routing and dispatch
+  middleware, must be an array itself, with the following structure:
 
   ```php
   [
@@ -59,6 +57,7 @@ order to seed the `Application` instance:
       // optional:
       'path'  => '/path/to/match',
       'error' => true,
+      'priority' => 1, // Integer
   ],
   ```
 
@@ -69,7 +68,16 @@ order to seed the `Application` instance:
   `error` key is present and boolean `true`, then the middleware will be
   registered as error middleware. (This is necessary due to the fact that the
   factory defines a callable wrapper around middleware to enable lazy-loading of
-  middleware.)
+  middleware.) The `priority` defaults to 1, and follows the semantics of
+  [SplPriorityQueue](http://php.net/SplPriorityQueue): higher integer values
+  indicate higher priority (will execute earlier), while lower/negative integer
+  values indicate lower priority (will execute last). Default priority is 1; use
+  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

@@ -86,22 +86,25 @@ From there, you still need to register the middleware. This middleware is not
 routed, and thus needs to be piped to the application instance. You can do this
 via either configuration, or manually.
 
-To do this via configuration, add an entry under the `post_routing` key of the
-`middleware_pipeline` configuration:
+To do this via configuration, add an entry under the `middleware_pipeline`
+configuration, after the dispatch middleware:
 
 ```php
 'middleware_pipeline' => [
-    'pre_routing' => [
-        [
-            //...
+    /* ... */
+    'routing' => [
+        'middleware' => [
+            Zend\Expressive\Container\ApplicationFactory::ROUTING_MIDDLEWARE,
+            Zend\Expressive\Helper\UrlHelperMiddleware::class,
+            Zend\Expressive\Container\ApplicationFactory::DISPATCH_MIDDLEWARE,
         ],
-
+        'priority' => 1,
     ],
-    'post_routing' => [
-        [
-            'middleware' => 'Application\NotFound',
-        ],
+    [
+        'middleware' => 'Application\NotFound',
+        'priority' => -1,
     ],
+    /* ... */
 ],
 ```
 
@@ -117,9 +120,7 @@ $app->pipe($container->get('Application\NotFound'));
 
 This must be done *after*:
 
-- calling `$app->pipeRoutingMiddleware()`, **OR**
-- calling any method that injects routed middleware (`get()`, `post()`,
-  `route()`, etc.), **OR**
+- calling `$app->pipeDispatchMiddleware()`, **OR**
 - pulling the `Application` instance from the service container (assuming you
   used the `ApplicationFactory`).
 

doc/book/cookbook/debug-toolbars.md

@@ -74,12 +74,11 @@ return [
         ],
     ],
     'middleware_pipeline' => [
-        'pre_routing' => [
-            [
-                'middleware' => [
-                    PhpDebugBarMiddleware::class,
-                ],
+        [
+            'middleware' => [
+                PhpDebugBarMiddleware::class,
             ],
+            'priority' => 1000,
         ],
     ],
 ];

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

@@ -160,24 +160,23 @@ When either of these approaches are used, the individual middleware listed
 This approach is essentially equivalent to creating a factory that returns a
 middleware pipeline.
 
-## What about pre/post pipeline middleware?
+## What about pipeline middleware configuration?
 
-What if you want to do this with pre- or post-pipeline middleware? The answer is
-that the syntax is exactly the same!
+What if you want to do this with your pipeline middleware configuration? The
+answer is that the syntax is exactly the same!
 
 ```php
 return [
     'middleware_pipeline' => [
-        'pre_routing' => [
-            [
-                'path' => '/api',
-                'middleware' => [
-                    'AuthenticationMiddleware',
-                    'AuthorizationMiddleware',
-                    'BodyParsingMiddleware',
-                    'ValidationMiddleware',
-                ],
+        'api' => [
+            'path' => '/api',
+            'middleware' => [
+                'AuthenticationMiddleware',
+                'AuthorizationMiddleware',
+                'BodyParsingMiddleware',
+                'ValidationMiddleware',
             ],
+            'priority' => 100,
         ],
     ],
 ];