Concept¶

The ChainRouter¶

At the core of Symfony CMF's Routing component sits the ChainRouter. It is used as a replacement for Symfony2's default routing system and, like the Symfony2 router, is responsible for determining which Controller will handle each request.

The ChainRouter works by accepting a set of prioritized routing strategies, RouterInterface implementations, commonly referred to as "Routers". The routers are responsible for matching an incoming request to an actual Controller and, to do so, the ChainRouter iterates over the configured Routers according to their configured priority:

You can also load Routers using tagged services, by using the router tag and an optional priority. The higher the priority, the earlier your router will be asked to match the route. If you do not specify the priority, your router will come last. If there are several routers with the same priority, the order between them is undetermined. The tagged service will look like this:

The Symfony CMF Routing system adds a new DynamicRouter, which complements the default Router found in Symfony2.

The Default Symfony2 Router¶

Although it replaces the default routing mechanism, Symfony CMF Routing allows you to keep using the existing system. In fact, the standard Symfony2 routing is enabled by default, so you can keep using the routes you declared in your configuration files, or as declared by other bundles.

The DynamicRouter¶

This Router can dynamically load Route instances from a dynamic source via a so called provider. In fact it only loads candidate routes. The actual matching process is exactly the same as with the standard Symfony2 routing mechanism. However the DynamicRouter additionally is able to determine which Controller and Template to use based on the Route that is matched.

By default the DynamicRouter is disabled. To activate it, just add the following to your configuration file:

This is the minimum configuration required to load the DynamicRouter as a service, thus making it capable of performing routing. Actually, when you browse the default pages that come with the Symfony CMF SE, it is the DynamicRouter that matches your requests with the Controllers and Templates.

Linking a Route with a Model Instance¶

Depending on your application's logic, a requested URL may have an associated model instance from the database. Those Routes can implement the RouteObjectInterface, and optionally return a model instance, that will be automatically passed to the Controller as the contentDocument method parameter.

Note that a Route can implement the above mentioned interface but still not return any model instance, in which case no associated object will be provided.

Furthermore, Routes that implement this interface can also provide their own name with the getRouteKey method. For normal Symfony routes, the name is only known from their key in the RouteCollection collection hashmap. In the CMF, it is possible to use route documents outside of collections, and thus useful to have routes provide their name. The PHPCR routes for example return the repository path when this method is called.

Redirects¶

You can build redirects by implementing the RedirectRouteInterface. If you are using the default PHPCR-ODM route provider, a ready to use implementation is provided in the RedirectRoute Document. It can redirect either to an absolute URI, to a named Route that can be generated by any Router in the chain or to another Route object known to the route provider. The actual redirection is handled by a specific Controller that can be configured as follows:

URL Generation¶

Symfony CMF's Routing component uses the default Symfony2 components to handle route generation, so you can use the default methods for generating your URLs with a few added possibilities:

• Pass an implementation of either RouteObjectInterface or RouteReferrersInterface as the name parameter
• Alternatively, supply an implementation of ContentRepositoryInterface and the id of the model instance as parameter content_id

See URL generation with the DynamicRouter for code examples of all above cases.

The route generation handles locales as well, see "ContentAwareGenerator and Locales".

The PHPCR-ODM Route Document¶

As mentioned above, you can use any route provider. The example in this section applies if you use the default PHPCR-ODM route provider (Symfony\Cmf\Bundle\RoutingBundle\Doctrine\Phpcr\RouteProvider).

PHPCR-ODM documents are stored in a tree, and their ID is the path in that tree. To match routes, a part of the repository path is used as URL. To avoid mixing routes and other documents, routes are placed under a common root path and that path is removed from the ID to build the URL. The common root path is called "route basepath". The default base path is /cms/routes. A new route can be created in PHP code as follows:

 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

// src/Acme/MainBundle/DataFixtures/PHPCR/LoadRoutingData.php
namespace Acme\DemoBundle\DataFixtures\PHPCR;

use Doctrine\ODM\PHPCR\DocumentManager;
use Doctrine\Common\DataFixtures\FixtureInterface;
use Doctrine\Common\Persistence\ObjectManager;
use Symfony\Cmf\Bundle\RoutingBundle\Doctrine\Phpcr\Route;
use Symfony\Cmf\Bundle\ContentBundle\Doctrine\Phpcr\StaticContent;
use PHPCR\Util\NodeHelper;

class LoadRoutingData implements FixtureInterface
{
    /**
     * @param DocumentManager $dm
     */
    public function load(ObjectManager $dm)
    {
        if (!$dm instanceof DocumentManager) {
            $class = get_class($dm);
            throw new \RuntimeException("Fixture requires a PHPCR ODM DocumentManager instance, instance of '$class' given.");
        }

        $session = $dm->getPhpcrSession();
        NodeHelper::createPath($session, '/cms/routes');

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

        // link a content to the route
        $content = new StaticContent();
        $content->setParentDocument($dm->find(null, '/cms/content'));
        $content->setName('my-content');
        $content->setTitle('My Content');
        $content->setBody('Some Content');
        $dm->persist($content);
        $route->setContent($content);

        $dm->persist($route);
        $dm->flush();
    }
}

Now the CMF will be able to handle requests for the URL /my-content.

Because you called setContent on the route, the controller can expect the $contentDocument parameter. You can now configure which controller should handle StaticContent as explained above.

The PHPCR-ODM routes support more things, for example route parameters, requirements and defaults. This is explained in the route document section in the RoutingBundle documentation. You can also find route entity documentation and Doctrine ORM integration.

Further Notes¶

For more information on the Routing component of Symfony CMF, please refer to:

• Routing for most of the actual functionality implementation
• RoutingBundle for Symfony2 integration bundle for Routing Bundle
• Symfony2's Routing component page
• Handling Multi-Language Documents for some notes on multilingual routing