Dynamic Router

Configuration

The minimum configuration required to load the dynamic router is to specify a route provider backend and to register the dynamic router in the chain of routers.

1
2
3
4
5
6
7
8
9
10

# app/config/packages/cmf_routing.yaml
cmf_routing:
    chain:
        routers_by_id:
            router.default: 200
            cmf_routing.dynamic_router: 100
    dynamic:
        persistence:
            phpcr:
                enabled: true

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<!-- app/config/packages/cmf_routing.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services">
    <config xmlns="http://cmf.symfony.com/schema/dic/routing">
        <chain>
            <router-by-id id="router.default">200</router-by-id>
            <router-by-id id="cmf_routing.dynamic_router">100</router-by-id>
        </chain>
        <dynamic>
            <persistence>
                <phpcr enabled="true" />
            </persistence>
        </dynamic>
    </config>
</container>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// app/config/packages/cmf_routing.php
$container->loadFromExtension('cmf_routing', [
    'chain' => [
        'routers_by_id' => [
            'router.default' => 200,
            'cmf_routing.dynamic_router' => 100,
        ],
    ],
    'dynamic' => [
        'persistence' => [
            'phpcr' => [
                'enabled' => true,
            ],
        ],
    ],
]);

When there is no configuration or cmf_routing.dynamic.enabled is set to false, the dynamic router services will not be loaded at all, allowing you to use the ChainRouter with your own routers.

Match Process

Most of the match process is described in the documentation of the CMF Routing component. The only difference is that this bundle will place the contentDocument into the request attributes instead of into the route defaults to avoid issues when generating the URL for the current request.

Your controllers can (and should) declare the parameter $contentDocument in their Action methods if they are supposed to work with content referenced by the routes. Note that the ContentBundle (no longer maintained) provides a default controller that renders the content with a specified template for when you do not need any logic.

A custom controller action can look like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

// src/AppBundle/Controller/ContentController.php
namespace AppBundle\Controller;

use Symfony\Component\HttpFoundation\Response;
use Symfony\Bundle\FrameworkBundle\Controller\Controller;

/**
 * A custom controller to handle a content specified by a route.
 */
class ContentController extends Controller
{
    /**
     * @param object $contentDocument the name of this parameter is defined
     *      by the RoutingBundle. You can also expect any route parameters
     *      or $template if you configured templates_by_class (see below).
     *
     * @return Response
     */
    public function demoAction($contentDocument)
    {
        // ... do things with $contentDocument and gather other information
        $customValue = 42;

        return $this->render('content/demo.html.twig', [
            'cmfMainContent' => $contentDocument,
            'custom_parameter' => $customValue,
        ]);
    }
}

Configuring the Controller for a Route

To configure what controller is used for which route, you can configure the route enhancers. Many of them operate on routes implementing RouteObjectInterface. This interface tells that the route knows about its content and returns it by the method getRouteContent(). (See CMF Routing component if you want to know more about this interface.)

The possible enhancements that take place, if configured, are (in order of precedence):

1. (Explicit controller): If there is a _controller set in getRouteDefaults(), no enhancer will overwrite the controller. _template will still be inserted if its not already set;
2. controllers_by_type: requires the route document to return a 'type' value in getRouteDefaults(). priority: 60;
3. controllers_by_class: requires the route document to be an instance of RouteObjectInterface and to return an object for getRouteContent(). The content document is checked for being instanceof the class names in the map and if matched that controller is used. Instanceof is used instead of direct comparison to work with proxy classes and other extending classes. priority: 50;
4. templates_by_class: requires the route document to be an instance of RouteObjectInterface and to return an object for getRouteContent(). The content document is checked for being instanceof the class names in the map and if matched that template will be set as '_template'. priority: 40 for the template, generic controller is set at priority: 30;
5. If a _template is in the $defaults but no controller was determined so far (neither set on the route nor matched in controller by type or class), the generic controller is chosen. priority: 10;
6. The default controller is chosen. This controller can use a default template to render the content, which will likely further decide how to handle this content. See also the ContentBundle documentation. priority: -100.

See the configuration reference to learn how to configure these enhancers.

If the ContentBundle is present in your application, the generic and default controllers default to the ContentController provided by that bundle.

Doctrine PHPCR-ODM Integration

The RoutingBundle comes with a route provider implementation for PHPCR-ODM. PHPCR is well suited to the tree nature of the data. If you use PHPCR-ODM with a route document like the one provided, you can just leave the provider service at the default.

The default provider loads the route at the path in the request and all parent paths to allow for some of the path segments being parameters. If you need a different way to load routes or for example never use parameters, you can write your own provider implementation to optimize by implementing the RouteProviderInterface with your own service and specify that service as cmf_routing.dynamic.route_provider_service_id.

1
2
3
4
5
6
7
8

use Symfony\Cmf\Bundle\RoutingBundle\Doctrine\Phpcr\Route;

$route = new Route();
$route->setParentDocument($dm->find(null, '/cms/routes'));
$route->setName('projects');

// set explicit controller
$route->setDefault('_controller', 'app.controller::specialAction');

1
2
3
4
5

use Symfony\Cmf\Bundle\ContentBundle\Doctrine\Phpcr\Content;

// ...
$content = new Content('my content'); // Content must be a mapped class
$route->setRouteContent($content);

1
2
3
4

// do not forget leading slash if you want /projects/{id} and not /projects{id}
$route->setVariablePattern('/{id}');
$route->setRequirement('id', '\d+');
$route->setDefault('id', 1);

1
2
3

$route->setVariablePattern('/{context}/item/{id}');
$route->setRequirement('context', '[a-z]+');
$route->setRequirement('id', '\d+');

Doctrine ORM integration

Alternatively, you can use the Doctrine ORM provider by specifying the persistence.orm part of the configuration. It does a similar job but, as the name indicates, loads Route entities from an ORM database.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

// 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();
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

// 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;
    }
}

Locales and Route Objects

Neither PHPCR-ODM nor ORM routes should be translated documents themselves. A route represents one single url, and serving several translations under the same url is not recommended.

Make sure you configure the valid locales in the configuration so that the bundle can optimally handle locales. The configuration reference lists some options to tweak behavior and performance.

For multilingual websites, you have two options: One route object per language with the _locale set as default; A single route with the option add_locale_pattern.

URL generation with the DynamicRouter

Apart from matching an incoming request to a set of parameters, a Router is also responsible for generating an URL from a route and its parameters. The DynamicRouter adds more power to the URL generating capabilities of Symfony.

You can use a Route object directly with the router:

1
2

{# myRoute is an object of class Symfony\Component\Routing\Route #}
<a href="{{ path('cmf_routing_object', {_route_object: myRoute}) }}">Read on</a>

1
2
3
4
5
6
7

<!-- $myRoute is an object of class Symfony\Component\Routing\Route -->
<a href="<?php echo $view['router']->generate(
    RouteObjectInterface::OBJECT_BASED_ROUTE_NAME,
    [RouteObjectInterface::ROUTE_OBJECT => $myRoute])
?>">
    Read on
</a>

When using the PHPCR-ODM persistence layer, the repository path of the route document is considered the route name. Thus you can specify a repository path to generate a route:

1
2

{# Create a link to / on this server #}
<a href="{{ path('/cms/routes') }}>Home</a>

1
2
3
4

<!-- Create a link to / on this server -->
<a href="<?php echo $view['router']->generate('/cms/routes') ?>">
    Home
</a>

The DynamicRouter uses a URL generator that operates on the RouteReferrersInterface. This means you can also generate a route from any object that implements this interface and provides a route for it:

1
2

{# myContent implements RouteReferrersInterface #}
<a href="{{ path('cmf_routing_object', {_route_object: myContent}) }}>Read on</a>

1
2
3
4
5
6
7

<!-- $myContent implements RouteReferrersInterface -->
<a href="<?php echo $view['router']->generate(
    RouteObjectInterface::OBJECT_BASED_ROUTE_NAME,
    [RouteObjectInterface::ROUTE_OBJECT => $myContent])
?>">
    Home
</a>

Additionally, the generator also understands the content_id parameter with an empty route name and tries to find a content implementing the RouteReferrersInterface from the configured content repository:

1
2
3

<a href="{{ path('cmf_routing_object', {'content_id': '/cms/content/my-content'}) }}>
    Read on
</a>

1
2
3
4
5
6

<!-- $myContent implements RouteReferrersInterface -->
<a href="<?php echo $view['router']->generate('cmf_routing_object', [
    'content_id' => '/cms/content/my-content',
]) ?>">
    Home
</a>

For the implementation details, please refer to the Dynamic Router section in the the cmf routing component documentation.

Handling RedirectRoutes

This bundle also provides a controller to handle RedirectionRouteInterface documents. You need to configure the route enhancer for this interface:

1
2
3
4
5

# app/config/packages/cmf_routing.yaml
cmf_routing:
    dynamic:
        controllers_by_class:
            Symfony\Cmf\Component\Routing\RedirectRouteInterface: cmf_routing.redirect_controller::redirectAction

1
2
3
4
5
6
7
8
9
10
11

<!-- app/config/packages/cmf_routing.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services">
    <config xmlns="http://cmf.symfony.com/schema/dic/routing">
        <dynamic>
            <controller-by-class class="Symfony\Cmf\Component\Routing\RedirectRouteInterface">
                cmf_routing.redirect_controller::redirectAction
            </controller-by-class>
        </dynamic>
    </config>
</container>

1
2
3
4
5
6
7
8
9
10

// app/config/packages/cmf_routing.php
use Symfony\Cmf\Bundle\Routing\RedirectRouteInterface;

$container->loadFromExtension('cmf_routing', [
    'dynamic' => [
        'controllers_by_class' => [
            RedirectRouteInterface::class => 'cmf_routing.redirect_controller::redirectAction',
        ],
    ],
]);

Customize the DynamicRouter

Read on in the chapter customizing the dynamic router.