Add a context resource

docs/04. Controllers.md

@@ -117,6 +117,28 @@ where setting `autoHydrate` to false makes sense, it is not recommended to set `
 you will receive potentially malicious data. It's therefore up to you to manually validate and filter your data
 if you turn off this option!
 
+## Context resource
+
+When dealing with requests such as POST `/users/1/tweets`, you will receive a Tweet instance as the parameter
+of the POST method in the tweet controller. However, you may need to have the context that was used to match
+this resource. In this case, the user n°1.
+
+Because the router traverses the whole path, it keeps track of all the matched resources. ZfrRest controllers offer
+a simple way to retrieve the previous matched resource (aka. the context) through the use of the `getContextResource`
+method:
+
+```php
+class TweetListController extends AbstractRestfulController
+{
+    public function post(Tweet $tweet)
+    {
+        $userResource = $this->getContextResource(); // $userResource is a ResourceInterface object
+    }
+}
+```
+
+ZfrRest only supports going back one level in the hierarchy.
+
 ### Navigation
 
 * Continue to [**Built-in listeners**](/docs/05. Built-in listeners.md)

src/ZfrRest/Mvc/Controller/AbstractRestfulController.php

@@ -108,6 +108,14 @@ public function getMatchedResource()
         return $this->getEvent()->getRouteMatch()->getParam('resource', null);
     }
 
+    /**
+     * @return ResourceInterface|null
+     */
+    public function getContextResource()
+    {
+        return $this->getEvent()->getRouteMatch()->getParam('context', null);
+    }
+
     /**
      * Get the method handler plugin manager
      *

src/ZfrRest/Router/Http/ResourceGraphRoute.php

@@ -30,6 +30,7 @@
 use ZfrRest\Resource\ResourceInterface;
 use ZfrRest\Router\Exception\RuntimeException;
 use ZfrRest\Router\Http\Matcher\BaseSubPathMatcher;
+use ZfrRest\Router\Http\Matcher\SubPathMatch;
 
 /**
  * @license MIT
@@ -169,19 +170,20 @@ public function match(RequestInterface $request, $pathOffset = 0)
             ], strlen($path));
         }
 
-        return $this->buildRouteMatch($match->getMatchedResource(), strlen($path));
+        return $this->buildRouteMatch($match, strlen($path));
     }
 
     /**
      * Build a route match
      *
-     * @param  ResourceInterface $resource
-     * @param  int               $pathLength
+     * @param  SubPathMatch $match
+     * @param  int          $pathLength
      * @throws RuntimeException
      * @return RouteMatch
      */
-    protected function buildRouteMatch(ResourceInterface $resource, $pathLength)
+    protected function buildRouteMatch(SubPathMatch $match, $pathLength)
     {
+        $resource = $match->getMatchedResource();
         $metadata = $resource->getMetadata();
 
         // If returned $data is a collection, then we use the controller specified in Collection mapping
@@ -196,9 +198,12 @@ protected function buildRouteMatch(ResourceInterface $resource, $pathLength)
             $controllerName = $metadata->getControllerName();
         }
 
+        $previousMatch = $match->getPreviousMatch();
+
         return new RouteMatch(
             [
                 'resource'   => $resource,
+                'context'    => $previousMatch ? $previousMatch->getMatchedResource() : null,
                 'controller' => $controllerName
             ],
             $pathLength