ORM routes and routing auto adapter

Author: pcabreus

book/routing.rst

@@ -520,6 +520,7 @@ handle ``StaticContent`` as :ref:`explained above <start-routing-getting-control
 The PHPCR-ODM routes support more things, for example route parameters,
 requirements and defaults. This is explained in the
 :ref:`route document section in the RoutingBundle documentation <bundle-routing-document>`.
+You can also find :ref:`route entity documentation and Doctrine ORM integration <bundle-routing-entity>`.
 
 Further Notes
 -------------

bundles/map.rst.inc

@@ -60,6 +60,8 @@ library or they introduce a complete new concept.
   * :doc:`routing_auto/token_providers`
   * :doc:`routing_auto/conflict_resolvers`
   * :doc:`routing_auto/defunct_route_handlers`
+  * :doc:`routing_auto/adapter`
+  * :doc:`routing_auto/configuration`
 
 * :doc:`search/index`
 

bundles/routing/dynamic.rst

@@ -408,6 +408,151 @@ the name indicates, loads ``Route`` entities from an ORM database.
     You must install the CoreBundle to use this feature if your application
     does not have at least DoctrineBundle 1.3.0.
 
+.. _bundle-routing-route-entity:
+
+The ORM Route entity
+--------------------
+
+The example in this section applies if you use the ORM route provider
+(``Symfony\Cmf\Bundle\RoutingBundle\Doctrine\Orm\RouteProvider``). It uses the
+``staticPrefix`` field of the
+``Symfony\Cmf\Bundle\RoutingBundle\Doctrine\Orm\Route`` to find route candidates.
+
+Symfony Cmf routing system allows us loading whatever content from a route.
+That means an entity route can reference to different types of entities.
+But Doctrine ORM is not able to establish that kind of mapping associations.
+To do that, the ORM RouteProvider follows the pattern of FQN:id. That is, the full
+model class name, then a colon, then the id. You only need to add it to the
+defaults parameters of the route with the ``RouteObjectInterface::CONTENT_ID``
+key. ``cmf_routing.content_repository`` service can help you to do it easily.
+A new route can be created in PHP code as follows::
+
+    // src/AppBundle/DataFixtures/ORM/LoadPostData.php
+    namespace AppBundle\DataFixtures\ORM;
+
+    use AppBundle\Entity\Post;
+    use Doctrine\Common\DataFixtures\FixtureInterface;
+    use Doctrine\Common\Persistence\ObjectManager;
+    use Symfony\Cmf\Bundle\RoutingBundle\Doctrine\Orm\Route;
+    use Symfony\Cmf\Component\Routing\RouteObjectInterface;
+    use Symfony\Component\DependencyInjection\ContainerAwareInterface;
+    use Symfony\Component\DependencyInjection\ContainerAwareTrait;
+
+    class LoadPostData implements FixtureInterface, ContainerAwareInterface
+    {
+        use ContainerAwareTrait;
+
+        /**
+         * @param ObjectManager $manager
+         */
+        public function load(ObjectManager $manager)
+        {
+            $post = new Post();
+            $post->setTitle('My Content');
+            $manager->persist($post);
+            $manager->flush(); // flush to be able to use the generated id
+
+            $contentRepository = $this->container->get('cmf_routing.content_repository');
+
+            $route = new Route();
+            $route->setName('my-content');
+            $route->setStaticPrefix('/my-content');
+            $route->setDefault(RouteObjectInterface::CONTENT_ID, $contentRepository->getContentId($post));
+            $route->setContent($post);
+            $post->addRoute($route); // Create the backlink from content to route
+
+            $manager->persist($post);
+            $manager->flush();
+        }
+    }
+
+Now the CMF will be able to handle requests for the URL ``/my-content``.
+
+.. caution::
+
+    Make sure that the content already has an id before you set it on the route.
+    The route to content link only works with single column ids.
+
+The ``Post`` entity content in this example could be like this::
+
+    // src/AppBundle/Entity/Post.php
+    namespace AppBundle\Entity;
+
+    use Doctrine\Common\Collections\ArrayCollection;
+    use Doctrine\ORM\Mapping as ORM;
+    use Symfony\Cmf\Component\Routing\RouteObjectInterface;
+    use Symfony\Cmf\Component\Routing\RouteReferrersInterface;
+
+    /**
+     * @ORM\Table(name="post")
+     * @ORM\Entity(repositoryClass="AppBundle\Repository\PostRepository")
+     */
+    class Post implements RouteReferrersInterface
+    {
+        /** .. fields like title and body */
+
+        /**
+         * @var RouteObjectInterface[]|ArrayCollection
+         *
+         * @ORM\ManyToMany(targetEntity="Symfony\Cmf\Bundle\RoutingBundle\Doctrine\Orm\Route", cascade={"persist", "remove"})
+         */
+        private $routes;
+
+        public function __construct()
+        {
+            $this->routes = new ArrayCollection();
+        }
+
+        /**
+         * @return RouteObjectInterface[]|ArrayCollection
+         */
+        public function getRoutes()
+        {
+            return $this->routes;
+        }
+
+        /**
+         * @param RouteObjectInterface[]|ArrayCollection $routes
+         */
+        public function setRoutes($routes)
+        {
+            $this->routes = $routes;
+        }
+
+        /**
+         * @param RouteObjectInterface $route
+         *
+         * @return $this
+         */
+        public function addRoute($route)
+        {
+            $this->routes[] = $route;
+
+            return $this;
+        }
+
+        /**
+         * @param RouteObjectInterface $route
+         *
+         * @return $this
+         */
+        public function removeRoute($route)
+        {
+            $this->routes->removeElement($route);
+
+            return $this;
+        }
+    }
+
+Because you set the ``content_id`` default value on the route, the controller
+can expect the ``$contentDocument`` parameter. You can now configure which
+controller should handle ``Post`` entities as explained in the
+:ref:`Routing documentation <start-routing-getting-controller-template>`.
+
+The ORM routes support more things, for example route parameters, requirements
+and defaults. This is explained in the
+:ref:`route document section <bundle-routing-document>`.
+
 .. _bundles-routing-dynamic-generator:
 
 URL generation with the DynamicRouter

bundles/routing_auto/adapter.rst

@@ -0,0 +1,85 @@
+.. index::
+    single: Adapter; RoutingAutoBundle
+
+Adapter
+=======
+
+Adapters abstract persistence operations. The ``PhpcrOdmAdapter`` is available
+for the Doctrine PHPCR-ODM persistence layer. If you want to use a different
+persistence layer, you need to implement your own adapter.
+
+Implementing a custom adapter
+-----------------------------
+
+Adapters have to implement ``Symfony\Cmf\Component\RoutingAuto\AdapterInterface``::
+
+    // src/AppBundle/Adapter/CustomAdapter.php
+    namespace AppBundle\Adapter;
+
+    use Symfony\Cmf\Component\RoutingAuto\AdapterInterface;
+
+    class OrmAdapter implements AdapterInterface
+    {
+        // ... Implement all methods defined by the interface
+    }
+
+Adapters need to be registered as services and tagged with
+``cmf_routing_auto.adapter`` and an ``alias`` to identify the adapter:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        services:
+            app.custom_adapter:
+                class: AppBundle\RoutingAuto\CustomAdapter
+                tags:
+                    - { name: cmf_routing_auto.adapter, alias: "custom_adapter"}
+
+    .. code-block:: xml
+
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services">
+            <service
+                id="app.custom_adapter"
+                class="AppBundle\RoutingAuto\CustomAdapter"
+            >
+                <tag name="cmf_routing_auto.adapter" alias="custom_adapter"/>
+            </service>
+        </container>
+
+    .. code-block:: php
+
+        use Symfony\Component\DependencyInjection\Definition;
+        use AppBundle\RoutingAuto\CustomAdapter;
+
+        $definition = new Definition(CustomAdapter::class);
+        $definition->addTag('cmf_routing_auto.adapter', array('alias' => 'custom_adapter'));
+
+        $container->setDefinition('app.custom_adapter', $definition);
+
+To use the new adapter, you specify the alias in the routing auto configuration:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+        cmf_routing_auto:
+            adapter: custom_adapter
+
+    .. code-block:: xml
+
+        <!-- app/config/config.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services">
+            <config xmlns="http://cmf.symfony.com/schema/dic/routingauto"
+                adapter="custom_adapter"
+            />
+        </container>
+
+    .. code-block:: php
+
+        $container->loadFromExtension('cmf_routing_auto', array(
+            'adapter' => 'custom_adapter',
+        ));

bundles/routing_auto/configuration.rst

@@ -0,0 +1,31 @@
+Configuration Reference
+=======================
+
+The RoutingAutoBundle can be configured under the ``cmf_routing_auto`` key in your
+application configuration.
+
+Configuration
+-------------
+
+``adapter``
+~~~~~~~~~~~
+
+**type**: ``scalar`` **default**: ``doctrine_phpcr_odm`` if ``persistence`` configuration option is set ``phpcr``
+
+This defines the adapter used to manage routes.
+
+``auto_mapping``
+~~~~~~~~~~~~~~~~
+
+**type**: ``boolean`` **default**: ``true``
+
+Look for the configuration file ``cmf_routing_auto.yml`` in `Resource/config` folder of all
+available bundles.
+
+``persistence``
+~~~~~~~~~~~~~~~
+
+``phpcr``
+.........
+
+.. todo

bundles/routing_auto/index.rst

@@ -9,3 +9,5 @@ RoutingAutoBundle
     conflict_resolvers
     defunct_route_handlers
     definitions
+    adapter
+    configuration

bundles/routing_auto/introduction.rst

@@ -191,6 +191,8 @@ Read more
 * :doc:`conflict_resolvers`
 * :doc:`defunct_route_handlers`
 * :doc:`definitions`
+* :doc:`adapter`
+* :doc:`configuration`
 
 .. _`with composer`: https://getcomposer.org/
 .. _`symfony-cmf/routing-auto-bundle`: https:/packagist.org/packages/symfony-cmf/routing-auto-bundle