renaming DoctrineRouter to DynamicRouter to reflect this does not depend on doctrine. cleanup interfacing with the Mapper

Author: dbu

ContentRepositoryInterface.php

@@ -3,9 +3,11 @@
 namespace Symfony\Cmf\Component\Routing;
 
 /**
- * Interface used by the DoctrineRouter to retrieve content by it's id.
+ * Interface used by the DynamicRouter to retrieve content by it's id when
+ * generating routes from content-id.
  *
- * This can be easily implemented using the DocumentManager.
+ * This can be easily implemented using i.e. the Doctrine PHPCR-ODM
+ * DocumentManager.
  *
  * @author Uwe Jäger
  */
@@ -14,9 +16,12 @@ interface ContentRepositoryInterface
     /**
      * Return a content object by it's id or null if there is none.
      *
-     * @abstract
-     * @param $id id of the content object
-     * @return mixed
+     * If the returned content implements RouteAwareInterface, it will be used
+     * to get the route from it to generate an URL.
+     *
+     * @param string $id id of the content object
+     *
+     * @return object A content that matches this id.
      */
     function findById($id);
 }

DoctrineRouter.php renamed to DynamicRouter.php

@@ -13,41 +13,42 @@
 
 use Symfony\Cmf\Component\Routing\Mapper\ControllerMapperInterface;
 
-use Doctrine\Common\Persistence\ManagerRegistry;
-use Doctrine\Common\Persistence\ObjectManager;
-
 /**
- * A router that reads route entries from an Object-Document Mapper store.
+ * A router that reads route entries from a repository. The repository can
+ * easily be implemented using an object-document mapper like Doctrine
+ * PHPCR-ODM but you are free to use something different.
  *
- * This is basically using the symfony routing matcher and generator. Different
+ * This router is based on the symfony routing matcher and generator. Different
  * to the default router, the route collection is loaded from the injected
  * route repository custom per request to not load a potentially large number
  * of routes that are known to not match anyways.
  *
  * If the route provides a content, that content is placed in the defaults
- * returned by the match() method in field '_content'.
+ * returned by the match() method in field RouteObjectInterface::CONTENT_OBJECT.
  *
  * @author Philippo de Santis
  * @author David Buchmann
  * @author Uwe Jäger
  */
-class DoctrineRouter implements RouterInterface
+class DynamicRouter implements RouterInterface
 {
     /**
      * Symfony routes always need a name in the collection. We generate routes
      * based on the route object, but need to use a name for example in error
      * reporting.
-     * When generating, we just use this prefix, when matching, we add the full
-     * repository path with "/" replaced by "_" to get unique names.
+     * When generating, we just use this prefix, when matching, we append
+     * whatever the repository returned as ID, replacing anything but
+     * [^a-z0-9A-Z_.] with "_" to get unique valid route names.
      */
-    const ROUTE_NAME_PREFIX = 'cmf_routing_doctrine_route';
+    const ROUTE_NAME_PREFIX = 'cmf_routing_dynamic_route';
 
     /**
      * @var array of ControllerMapperInterface
      */
     protected $mappers = array();
     /**
      * The route repository to get routes from
+     *
      * @var RouteRepositoryInterface
      */
     protected $routeRepository;
@@ -170,7 +171,7 @@ public function getRouteCollection()
      *
      * array(
      *   "_controller" => "NameSpace\Controller::indexAction",
-     *   "reference" => $document,
+     *   "_content" => $document,
      * )
      *
      * The controller can be either the fully qualified class name or the
@@ -217,7 +218,7 @@ public function match($url)
         }
 
         if ($route instanceof RouteObjectInterface && $content = $route->getRouteContent()) {
-            $defaults['_content'] = $content;
+            $defaults[RouteObjectInterface::CONTENT_OBJECT] = $content;
         }
         $defaults['path'] = $url; // TODO: get rid of this
 
@@ -250,7 +251,7 @@ public function getMatcher(RouteCollection $collection)
      *
      * @param array $parameters which should contain a content field containing a RouteAwareInterface object
      *
-     * @return the route instance
+     * @return Route the route instance
      *
      * @throws RouteNotFoundException if there is no content field in the
      *      parameters or its not possible to build a route from that object

Mapper/ControllerAliasMapper.php

@@ -2,7 +2,7 @@
 
 namespace Symfony\Cmf\Component\Routing\Mapper;
 
-use Symfony\Cmf\Component\Routing\RouteObjectInterface;
+use Symfony\Component\Routing\Route;
 
 /**
  * Decide the controller by a map from alias to controller name injected into
@@ -30,7 +30,7 @@ public function __construct(array $controllersByAlias = array())
      *
      * {@inheritDoc}
      */
-    public function getController(RouteObjectInterface $document, array &$defaults)
+    public function getController(Route $route, array &$defaults)
     {
         if (! isset($defaults['type'])) {
             return false;

Mapper/ControllerClassMapper.php

@@ -2,6 +2,7 @@
 
 namespace Symfony\Cmf\Component\Routing\Mapper;
 
+use Symfony\Component\Routing\Route;
 use Symfony\Cmf\Component\Routing\RouteObjectInterface;
 
 /**
@@ -35,12 +36,17 @@ public function __construct(array $controllersByClass)
      *
      * @param array $defaults ignored
      */
-    public function getController(RouteObjectInterface $document, array &$defaults)
+    public function getController(Route $route, array &$defaults)
     {
-        $content = $document->getRouteContent();
+        if (! $route instanceof RouteObjectInterface) {
+            return false;
+        }
+
+        $content = $route->getRouteContent();
         if (null == $content) {
             return false;
         }
+
         // we need to loop over the array in case the content class extends the
         // specified class
         // i.e. phpcr-odm generates proxy class for the content.

Mapper/ControllerMapperInterface.php

@@ -2,10 +2,10 @@
 
 namespace Symfony\Cmf\Component\Routing\Mapper;
 
-use Symfony\Cmf\Component\Routing\RouteObjectInterface;
+use Symfony\Component\Routing\Route;
 
 /**
- * Interface for all controller mappers that work with the DoctrineRouter
+ * Interface for all controller mappers that work with the DynamicRouter
  *
  * @author David Buchmann
  */
@@ -14,14 +14,14 @@ interface ControllerMapperInterface
     /**
      * Retrieves the right controller for the given route $document.
      *
-     * @param RouteObjectInterface $document the document or entity for the route
+     * @param Route $route the document or entity for the route
      * @param array $defaults the getRouteDefaults array which may be altered by
      *      the mapper
      *
      * @return string the controller to use with this route object including
      *      the action, i.e. symfony_cmf_content.controller:indexAction
      *      or false if the mapper can not determine the router
      */
-    function getController(RouteObjectInterface $document, array &$defaults);
+    function getController(Route $route, array &$defaults);
 
 }

Mapper/ExplicitTemplateMapper.php

@@ -2,6 +2,8 @@
 
 namespace Symfony\Cmf\Component\Routing\Mapper;
 
+use Symfony\Component\Routing\Route;
+
 use Symfony\Cmf\Component\Routing\RouteObjectInterface;
 
 /**
@@ -37,7 +39,7 @@ public function __construct($genericController)
      *
      * {@inheritDoc}
      */
-    public function getController(RouteObjectInterface $document, array &$defaults)
+    public function getController(Route $document, array &$defaults)
     {
         if (! isset($defaults[RouteObjectInterface::TEMPLATE_NAME])) {
             return false;

Mapper/TemplateClassMapper.php

@@ -2,6 +2,7 @@
 
 namespace Symfony\Cmf\Component\Routing\Mapper;
 
+use Symfony\Component\Routing\Route;
 use Symfony\Cmf\Component\Routing\RouteObjectInterface;
 
 /**
@@ -51,9 +52,12 @@ public function __construct($genericController, array $templatesByClass = array(
      *
      * {@inheritDoc}
      */
-    public function getController(RouteObjectInterface $document, array &$defaults)
+    public function getController(Route $route, array &$defaults)
     {
-        $content = $document->getRouteContent();
+        if (! $route instanceof RouteObjectInterface) {
+            return false;
+        }
+        $content = $route->getRouteContent();
         if (null == $content) {
             return false;
         }

README.md

@@ -13,8 +13,10 @@ the Symfony2 router instance so you can still use the standard way for some of
 your routes.
 
 Additionally, this component is meant to provide useful router implementations.
-Currently, there is the *DoctrineRouter* that routes based on doctrine database
-entities or documents that extend Symfony2 Route objects.
+Currently, there is the *DynamicRouter* that routes based on a implemented
+repository that provide Symfony2 Route objects. The repository can be
+implemented using a database, for example with doctrine phpcr-odm or doctrine
+orm.
 
 **Note**: To use this component outside of the Symfony2 framework context, have
 a look at the [Symfony2 Routing component](https://github.com/symfony/Routing)
@@ -28,7 +30,7 @@ This component uses [composer](http://getcomposer.org). It needs the
 Symfony2 Routing component and the Symfony2 HttpKernel (for the logger
 interface and cache warmup interface).
 
-For the DoctrineRouter you will need something to implement the
+For the DynamicRouter you will need something to implement the
 RouteRepositoryInterface with. We suggest using Doctrine as this allows to map
 any class into a database.
 
@@ -40,14 +42,14 @@ chained routers. Add your router instances with the ``add`` method, then try
 to resolve routes with all added routers using the ``match`` method and
 Please refer to the phpdoc comments on the public methods for details.
 
-## Doctrine Router
+## Dynamic Router
 
 This implementation of a router loads routes from a RouteRepositoryInterface.
 This interface can be easily implemented with doctrine.
 The router works with the base UrlMatcher and UrlGenerator classes and only
 adds loading routes from the database and the concept of referenced content.
 
-To instantiate a DoctrineRouter, you need an implementation of the
+To instantiate a DynamicRouter, you need an implementation of the
 RouteRepositoryInterface. See the [Symfony2 RoutingExtraBundle](https://github.com/symfony-cmf/RoutingExtraBundle)
 document classes for an example.
 
@@ -57,7 +59,7 @@ content.
 
 ### Match Process
 
-The match method of the DoctrineRouter does the following steps
+The match method of the DynamicRouter does the following steps
 
 * Ask the repository for Route documents that could match the requested url
 * Build a route collection and let the UrlMatcher find a matching route
@@ -85,7 +87,7 @@ to Symfony\Cmf\Component\Routing\RedirectRouteInterface
 
 You can use the _locale default value in a route to create one route per locale
 that all reference the same multilingual content.
-The DoctrineRouter respects the _locale when generating routes from content.
+The DynamicRouter respects the _locale when generating routes from content.
 When resolving the route, the _locale gets into the request and is picked up
 by the symfony locale system.
 
@@ -99,7 +101,7 @@ under the same url is not a good idea.
 You can add more ControllerMapperInterface implementations if you have a case
 not handled by the provided ones.
 
-For more specific needs, have a look at DoctrineRouter and see if you want to
+For more specific needs, have a look at DynamicRouter and see if you want to
 extend it. You can also write your own routers to hook into the chain.
 
 ### Url generation

RedirectRouteInterface.php

@@ -12,18 +12,18 @@
  *
  * - uri: an absolute uri
  * - routeName and routeParameters: to be used with the standard symfony router
- *   or a route entry in the routeParameters for the DoctrineRouter. Precedency
+ *   or a route entry in the routeParameters for the DynamicRouter. Precedency
  *   between these is determined by the order of the routers in the chain
  *   router.
  *
  * With standard Symfony routing, you can just use uri / routeName and a
  * hashmap of parameters.
  *
- * For the doctrine router, you can return a RouteInterface instance in the
+ * For the dynamic router, you can return a RouteInterface instance in the
  * field 'route' of the parameters.
  *
  * Note: getRedirectContent must return the redirect route itself for the
- * integration with DoctrineRouter to work.
+ * integration with DynamicRouter to work.
  *
  * @author David Buchmann <[email protected]>
  */
@@ -56,7 +56,7 @@ function isPermanent();
     /**
      * Get the parameters for the target route router::generate()
      *
-     * Note that for the DoctrineRouter, you return the target route
+     * Note that for the DynamicRouter, you return the target route
      * document as field 'route' of the hashmap.
      *
      * @return array Information to build the route

RouteAwareInterface.php

@@ -4,7 +4,7 @@
 
 /**
  * Interface to be implemented by content that wants to be compatible with the
- * DoctrineRouter
+ * DynamicRouter
  */
 interface RouteAwareInterface
 {

RouteObjectInterface.php

@@ -3,9 +3,11 @@
 namespace Symfony\Cmf\Component\Routing;
 
 /**
- * Documents for entries in the routing table need to implement this interface
- * in addition to extending Symfony\Component\Routing\Route for the symfony router
- * so the DoctrineRouter can handle them.
+ * Classes for entries in the routing table may implement this interface in
+ * addition to extending Symfony\Component\Routing\Route.
+ *
+ * If they do, the DynamicRouter will request the route content and put it into
+ * the RouteObjectInterface::CONTENT_OBJECT field.
  *
  * Some fields in defaults have a special meaning in the getDefaults(). In addition
  * to the constants defined in this class, _locale and _controller are also used.
@@ -21,11 +23,16 @@ interface RouteObjectInterface
     const CONTROLLER_ALIAS = '_controller_alias';
 
     /**
-     * An explicit template to be used with this route.
+     * Field name for an explicit template to be used with this route.
      * i.e. SymfonyCmfContentBundle:StaticContent:index.html.twig
      */
     const TEMPLATE_NAME = '_template';
 
+    /**
+     * Field name for the content of the current route, if any.
+     */
+    const CONTENT_OBJECT = '_content';
+
     /**
      * Get the content document this route entry stands for. If non-null,
      * the ControllerClassMapper uses it to identify a controller and

RouteRepositoryInterface.php

@@ -3,7 +3,7 @@
 namespace Symfony\Cmf\Component\Routing;
 
 /**
- * Interface for the route provider the DoctrineRouter is using.
+ * Interface for the route provider the DynamicRouter is using.
  *
  * Typically this could be a doctrine orm or odm repository, but you can
  * implement something else if you need to.
@@ -14,7 +14,8 @@ interface RouteRepositoryInterface
      * Find routes that could match this absolute path.
      *
      * This may return a mixed list of class instances, but all routes returned
-     * must extend the core symfony route.
+     * must extend the core symfony route. The classes may also implement
+     * RouteObjectInterface to link to a content document.
      *
      * This method may not throw an exception based on implementation specific
      * restrictions on the url. That case is considered a not found - returning