Merge branch 'feature/route-result-subject'

Close #211

Author: weierophinney

CHANGELOG.md

@@ -17,16 +17,21 @@ Third release candidate.
   array **must** be callables, service names resolving to callable middleware,
   or fully qualified class names that can be instantiated without arguments, and
   which result in invokable middleware.
-- [#200](https://github.com/zendframework/zend-expressive/pull/200) and
-  [#206](https://github.com/zendframework/zend-expressive/pull/206) add a new
-  interface, `Zend\Expressive\RouteResultObserverInterface`.
-  `Zend\Expressive\Application` now also defines two methods,
-  `attachRouteResultObserver()` and `detachRouteResultObserver()`, which accept
-  instances of the interface. During `routeMiddleware()`, all observers are
-  updated immediately following the call to `RouterInterface::match()` with the
-  `RouteResult` instance. This feature enables the ability to notify objects of
-  the calculated `RouteResult` without needing to inject middleware into the
-  system.
+- [#200](https://github.com/zendframework/zend-expressive/pull/200),
+  [#206](https://github.com/zendframework/zend-expressive/pull/206), and
+  [#211](https://github.com/zendframework/zend-expressive/pull/211) add
+  functionality for observing computed `RouteResult`s.
+  `Zend\Expressive\Application` now implements
+  `Zend\Expressive\Router\RouteResultSubjectInterface`, which allows attaching
+  `Zend\Expressive\RouteResultObserverInterface` implementations and notifying
+  them of computed `RouteResult` instances. The following methods are now
+  available on the `Application` instance:
+  - `attachRouteResultObserver(Router\RouteResultObserverInterface $observer)`
+  - `detachRouteResultObserver(Router\RouteResultObserverInterface $observer)`
+  - `notifyRouteResultObservers(RouteResult $result)`; `Application` calls this
+    internally within `routeMiddleware`.
+  This feature enables the ability to notify objects of the calculated
+  `RouteResult` without needing to inject middleware into the system.
 - [#81](https://github.com/zendframework/zend-expressive/pull/81) adds a
   cookbook entry for creating 404 handlers.
 - [#210](https://github.com/zendframework/zend-expressive/pull/210) adds a

composer.json

@@ -20,7 +20,7 @@
         "container-interop/container-interop": "^1.1",
         "psr/http-message": "^1.0",
         "zendframework/zend-diactoros": "^1.1",
-        "zendframework/zend-expressive-router": "^1.0",
+        "zendframework/zend-expressive-router": "^1.1",
         "zendframework/zend-expressive-template": "^1.0.1",
         "zendframework/zend-stratigility": "^1.1"
     },

doc/book/router/result-observers.md

@@ -21,7 +21,7 @@ you to notify such utilities of the results of matching.
 Route result observers must implement the `RouteResultObserverInterface`:
 
 ```php
-namespace Zend\Expressive;
+namespace Zend\Expressive\Router;
 
 use Zend\Expressive\Router\RouteResult;
 
@@ -52,6 +52,16 @@ You can detach an existing observer as well, by passing its instance to the
 $app->detachRouteResultObserver($observer);
 ```
 
+> ### RouteResultSubjectInterface
+>
+> `Zend\Expressive\Application` implements `Zend\Expressive\Router\RouteResultSubjectInterface`,
+> which defines methods for attaching and detaching route result observers, as
+> well as a method for notifying observers. Typically you'll only see the
+> `Application` class as an implementation of the interface, but you can always
+> create your own implementations as well if desired — for instance, if
+> you are implementing your own middleware runtime using the various interfaces
+> Expressive provides.
+
 ## Example
 
 For this example, we'll build a simple URI generator. It will compose a
@@ -61,7 +71,7 @@ when invoked, generate a URI.
 ```php
 use Zend\Expressive\Router\RouterInterface;
 use Zend\Expressive\Router\RouteResult;
-use Zend\Expressive\RouteResultObserverInterface;
+use Zend\Expressive\ROuter\RouteResultObserverInterface;
 
 class UriGenerator implements RouteResultObserverInterface
 {

src/Application.php

@@ -29,7 +29,7 @@
  * @method Router\Route patch($path, $middleware, $name = null)
  * @method Router\Route delete($path, $middleware, $name = null)
  */
-class Application extends MiddlewarePipe
+class Application extends MiddlewarePipe implements Router\RouteResultSubjectInterface
 {
     /**
      * @var null|ContainerInterface
@@ -176,26 +176,38 @@ public function any($path, $middleware, $name = null)
     /**
      * Attach a route result observer.
      *
-     * @param RouteResultObserverInterface $observer
+     * @param Router\RouteResultObserverInterface $observer
      */
-    public function attachRouteResultObserver(RouteResultObserverInterface $observer)
+    public function attachRouteResultObserver(Router\RouteResultObserverInterface $observer)
     {
         $this->routeResultObservers[] = $observer;
     }
 
     /**
      * Detach a route result observer.
      *
-     * @param RouteResultObserverInterface $observer
+     * @param Router\RouteResultObserverInterface $observer
      */
-    public function detachRouteResultObserver(RouteResultObserverInterface $observer)
+    public function detachRouteResultObserver(Router\RouteResultObserverInterface $observer)
     {
         if (false === ($index = array_search($observer, $this->routeResultObservers, true))) {
             return;
         }
         unset($this->routeResultObservers[$index]);
     }
 
+    /**
+     * Notify all route result observers with the given route result.
+     *
+     * @param Router\RouteResult
+     */
+    public function notifyRouteResultObservers(Router\RouteResult $result)
+    {
+        foreach ($this->routeResultObservers as $observer) {
+            $observer->update($result);
+        }
+    }
+
     /**
      * Overload pipe() operation.
      *
@@ -692,16 +704,4 @@ private function marshalLazyErrorMiddlewareService($middleware, ContainerInterfa
             return $invokable($error, $request, $response, $next);
         };
     }
-
-    /**
-     * Notify all route result observers with the given route result.
-     *
-     * @param Router\RouteResult
-     */
-    private function notifyRouteResultObservers(Router\RouteResult $result)
-    {
-        foreach ($this->routeResultObservers as $observer) {
-            $observer->update($result);
-        }
-    }
 }

src/RouteResultObserverInterface.php

@@ -16,7 +16,7 @@
 use Zend\Diactoros\ServerRequest;
 use Zend\Expressive\Application;
 use Zend\Expressive\Router\RouteResult;
-use Zend\Expressive\RouteResultObserverInterface;
+use Zend\Expressive\Router\RouteResultObserverInterface;
 use Zend\Expressive\Router\RouterInterface;
 
 class RouteMiddlewareTest extends TestCase