1. Home
  2. Documentation
  3. Symfony CMF
  4. Configuration Reference

Configuration Reference

1.3 version
Maintained
1.3 current
Unmaintained
1.2
edit this page

Configuration Reference

The RoutingBundle can be configured under the cmf_routing key in your application configuration. When using XML, you can use the http://cmf.symfony.com/schema/dic/routing namespace.

Configuration

chain

routers_by_id

prototype: array default: { router.default: 100 }

This defines the routers to use in the chain. By default, only the Symfony2 router is used. The key is the name of the service and the value is the priority. The chain is sorted from the highest to the lowest priority.

To add the DynamicRouter, use the following configuration:

  • YAML
    1
2
3
4
5
    cmf_routing:
    chain:
        routers_by_id:
            cmf_routing.dynamic_router: 200
            router.default:             100
  • XML
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
    <?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="cmf_routing.dynamic_router">200</router-by-id>
            <router-by-id id="router.default">100</router-by-id>
        </chain>
    </config>

</container>
  • PHP
    1
2
3
4
5
6
7
8
    $container->loadFromExtension('cmf_routing', array(
    'chain' => array(
        'routers_by_id' => array(
            'cmf_routing.dynamic_router' => 200,
            'router.default'             => 100,
        ),
    ),
));

Tip

You can also add routers to the chain using the cmf_routing.router tag on a service, learn more in "Loading Routers with Tagging".

replace_symfony_router

type: Boolean default: true

If this option is set to false, the default Symfony2 router will not be overridden by the ChainRouter. By default, the ChainRouter will override the default Symfony2 router, but it will pass all requests to the default router, because no other routers were set.

  • YAML
    1
2
3
    cmf_routing:
    chain:
        replace_symfony_router: true
  • XML
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
    <?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services">

    <config xmlns="http://cmf.symfony.com/schema/dic/routing">
        <cmf-routing>
            <chain replace-symfony-router="true"/>
        </cmf-routing>
    </config>

</container>
  • PHP
    1
2
3
4
5
    $container->loadFromExtension('cmf_routing', array(
    'chain' => array(
        'replace_symfony_router' => true,
    ),
));

dynamic

enabled

type: Boolean default: false

Use this setting to activate the DynamicRouter. This will create a cmf_routing.dynamic_router service which you can add to the chain.

generic_controller

type: string default: null

The controller to use when the route enhancers only determined the template but no explicit controller. The value is the name of a controller using either the AcmeDemoBundle::Page::index or acme_demo.controller.page:indexAction notation.

If the CoreBundle and ContentBundle are registered, this defaults to cmf_content.controller:indexAction.

default_controller

type: string default: value of generic_controller

The default controller to use if none of the enhancers found a controller. The value is the name of a controller using either the AcmeDemoBundle::Page::index or acme_demo.controller.page:indexAction notation.

controllers_by_type

prototype: array

If the matching route has a type value in its defaults and no explicit controller is set, the route is handled by the controller configured for that type:

  • YAML
    1
2
3
4
    cmf_routing:
    dynamic:
        controllers_by_type:
            editable: acme_main.controller:editableAction
  • XML
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
    <?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-type type="editable">acme_main.controller:editableAction</controller-by-type>
        </dynamic>
    </config>

</container>
  • PHP
    1
2
3
4
5
6
7
    $container->loadFromExtension('cmf_routing', array(
    'dynamic' => array(
        'controllers_by_type' => array(
            'editable' => 'acme_main.controller:editableAction',
        ),
    ),
));

controllers_by_class

prototype: array

The controller to use when the matching route implements RouteObjectInterface and returns an object for getRouteContent(). This object is checked for being instanceof the class names in this map. instanceof is used instead of direct comparison to work with proxy classes and other extending classes. The order in which the classes are specified, matters. The first match is taken.

If matched, the controller will be set as _controller, making Symfony2 choose this controller to handle the request.

  • YAML
    1
2
3
4
    cmf_routing:
    dynamic:
        controllers_by_class:
            Symfony\Cmf\Bundle\ContentBundle\Document\StaticContent: cmf_content.controller:indexAction
  • XML
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
    <?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\Bundle\ContentBundle\Document\StaticContent">
                cmf_content.controller:indexAction
            </controller-by-class>
        </dynamic>
    </config>

</container>
  • PHP
    1
2
3
4
5
6
7
    $container->loadFromExtension('cmf_routing', array(
    'dynamic' => array(
        'controllers_by_class' => array(
            'Symfony\Cmf\Bundle\ContentBundle\Document\StaticContent' => 'cmf_content.controller:indexAction',
        ),
    ),
));

template_by_class

prototype: array

The template to use when the route implements RouteObjectInterface and returns an object for getRouteContent(). This object is checked for being instanceof the class names in this map. instanceof is used instead of direct comparison to work with proxy classes and other extending classes. The order in which the classes are specified, matters. The first match is taken.

If matched, the template will be set as _template in the defaults and unless another mapping specifies a controller, the generic_controller setting is set as controller.

  • YAML
    1
2
3
4
    cmf_routing:
    dynamic:
        templates_by_class:
            Symfony\Cmf\Bundle\ContentBundle\Document\StaticContent: CmfContentBundle:StaticContent:index.html.twig
  • XML
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
    <?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>
            <template-by-class
                class="Symfony\Cmf\Bundle\ContentBundle\Document\StaticContent">
                CmfContentBundle:StaticContent:index.html.twig
            </template-by-class>
        </dynamic>
    </config>

</container>
  • PHP
    1
2
3
4
5
6
7
    $container->loadFromExtension('cmf_routing', array(
    'dynamic' => array(
        'templates_by_class' => array(
            'Symfony\Cmf\Bundle\ContentBundle\Document\StaticContent' => 'CmfContentBundle:StaticContent:index.html.twig',
        ),
    ),
));

route_collection_limit

type: scalar, default: 0

If this value is set to a number bigger than 0, the routes from the database are returned in the getRouteCollection. The limit serves to prevent huge route lists if you have a large database. Setting the limit to false disables the limit entirely.

persistence

phpcr
  • YAML
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
    # app/config/config.yml
cmf_routing:
    dynamic:
        persistence:
            phpcr:
                enabled:      false
                manager_name: ~
                route_basepaths:
                    - /cms/routes
                    - /cms/simple
                content_basepath: /cms/content
                admin_basepath:   /cms/routes
                use_sonata_admin: auto
                enable_initializer: true
  • XML
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
    <!-- 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/routing">
        <dynamic>
            <persistence>
                <phpcr
                    enabled="false"
                    manager-name="null"
                    content-basepath="/cms/content"
                    admin-basepath="/cms/routes"
                    use-sonata-admin="auto"
                    enable_initializer="true"
                >
                    <route-basepath>/cms/routes</route-basepath>
                    <route-basepath>/cms/simple</route-basepath>
                </phpcr>
            </persistence>
        </dynamic>
    </config>
</container>
  • PHP
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
    $container->loadFromExtension('cmf_routing', array(
    'dynamic' => array(
        'persistence' => array(
            'phpcr' => array(
                'enabled'            => false,
                'manager_name'       => null,
                'route_basepaths'    => array(
                    '/cms/routes',
                    '/cms/simple',
                )
                'content_basepath'   => '/cms/content',
                'admin_basepath'     => '/cms/routes',
                'use_sonata_admin'   => 'auto',
                'enable_initializer' => true,
            ),
        ),
    ),
));
enabled

type: boolean default: false

If true, PHPCR is enabled in the service container.

If the CoreBundle is registered, this will default to the value of cmf_core.persistence.phpcr.enabled.

PHPCR can be enabled by multiple ways such as:

  • YAML
    1
2
3
4
5
6
    phpcr: ~ # use default configuration
# or
phpcr: true # straight way
# or
phpcr:
    manager: ... # or any other option under 'phpcr'
  • XML
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
    <persistence>
    <!-- use default configuration -->
    <phpcr />

    <!-- or setting it the straight way -->
    <phpcr>true</phpcr>

    <!-- or setting an option under 'phpcr' -->
    <phpcr manager="..." />
</persistence>
  • PHP
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    $container->loadFromExtension(..., array( // bundle configuration key, e.g. cmf_menu
    // ...
    'persistence' => array(
        'phpcr' => null, // use default configuration
        // or
        'phpcr' => true, // straight way
        // or
        'phpcr' => array(
            'manager' => '...', // or any other option under 'phpcr'
        ),
    ),
));
manager_name

type: string default: null

The name of the Doctrine Manager to use. null tells the manager registry to retrieve the default manager.

If the CoreBundle is registered, this will default to the value of cmf_core.persistence.phpcr.manager_name.

route_basepaths

New in version 1.3: The route_basepaths setting was introduced in version 1.3. Prior to 1.3, you could only configure one basepath using route_basepath.

type: string | array default: /cms/routes

A set of paths where routes are located in the PHPCR tree.

If the CoreBundle is registered, this will default to %cmf_core.persistence.phpcr.basepath%/routes. If the SimpleCmsBundle is registered as well, the SimpleCmsBundle basepath will be added as an additional route basepath.

content_basepath

type: string default: /cms/content

The basepath for content objects in the PHPCR tree. This information is used with the sonata admin to offer the correct subtree to select content documents.

If the CoreBundle is registered, this will default to %cmf_core.persistence.phpcr.basepath%/content.

admin_basepath

type: string default: first value of route_basepaths

The path at which to create routes with Sonata admin. There can be additional route basepaths, but you will need your own tools to edit those.

use_sonata_admin

type: enum valid values: true|false|auto default: auto

If true, the admin classes for the routing are loaded and available for sonata. If set to auto, the admin services are activated only if the SonataPhpcrAdminBundle is present.

Note

To see the route administration on the sonata dashboard, you still need to configure it to show the items cmf_routing.route_admin and cmf_routing.redirect_route_admin.

If the CoreBundle is registered, this will default to the value of cmf_core.persistence.phpcr.use_sonata_admin.

enable_initializer

type: boolean default: true

New in version 1.3: This configuration option was introduced in RoutingBundle 1.3.

The bundle comes with an initializer that creates the nodes for the admin_basepath automatically when initializing the repository or loading fixtures. Sometimes this is not what you want, as the created node is of type 'Generic' and sometimes this already needs to be a route (for the homepage). Set this to false to disable the initializer when you create your nodes your self (e.g. using Alice).

Caution

Initializers are forced to be disabled when Sonata Admin is not enabled. In such cases, you might have multiple route basepaths which are created by other sources. If the route basepath isn't created by another source, you have to configure an initializer.

orm
enabled

type: boolean default: false

If true, the ORM is included in the service container.

manager_name

type: string default: null

The name of the Doctrine Manager to use.

uri_filter_regexp

type: string default: ""

Sets a pattern to which the Route must match before attempting to get any routes from a database. This can improve the performance a lot when only a subsection of your site is using the dynamic router.

route_provider_service_id

type: string

When none of the persistence layers is enabled, a route provider service must be provided in order to get the routes. This is done by using the route_provider_service_id setting.

route_filters_by_id

prototype: array

This configures the route filters to use for filtering the route collection. The key is the id of the service and the value is the priority. The filters are sorted from the highest to the lowest priority.

  • YAML
    1
2
3
4
    cmf_routing:
    dynamic:
        route_filters_by_id:
            acme_main.routing.foo_filter: 100
  • XML
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
    <?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>
            <route-filter-by-id id="acme_main.routing.foo_filter">100</route-filter-by-id>
        </dynamic>
    </config>

</container>
  • PHP
    1
2
3
4
5
6
7
    $container->loadFromExtension('cmf_routing', array(
    'dynamic' => array(
        'route_filters_by_id' => array(
            'acme_main.routing.foo_filter' => 100,
        ),
    ),
));

content_repository_service_id

type: scalar default: null

To use a content repository when creating URLs, this option can be set to the content repository service.

Note

If PHPCR is enabled, it'll automatically use the phpcr content repository. This can be overridden by this option. ORM doesn't have a content repository at the moment.

url_generator

type: string default: cmf_routing.generator

Service id for the DynamicRouter to generate URLs from Route objects. Overwrite to a service implementing UrlGeneratorInterface if you need to customize that service.

locales

type: array default: array()

To enable multi-language, set the valid locales in this option.

If the CoreBundle is registered, this will default to the value of cmf_core.locales.

limit_candidates

type: integer default: 20

With this flag you can tune the routing behavior when using the dynamic pattern part of routes stored in the database. If you do never use the variable pattern field of the Route model, you can set this to 1 as a small performance optimization. If you have very complex URLs with patterns, you might need to increase the limit.

Caution

Setting this to a higher makes your site more vulnerable to load attacks when someone visits your site with URLs with lots of slashes in them, since every slash will lead to a document being tried to be loaded.

match_implicit_locale

type: boolean default: true

Whether the route provider should look for routes without the locale.

For example, when the locales are de and en and the request has the url de/my/path, the route provider will not only look for de/my/path, de/my and de but also for my/path and my. This allows to use a single route for multiple languages. This is used for example by the SimpleCms.

If you do not need this, disabling the option will gain some performance.

auto_locale_pattern

type: boolean default: false

If you enable this option, the LocaleListener will ensure that routes that have no locale in their static pattern get the auto_locale_pattern option set.

Note

Enabling this option will prevent you from having any CMF Routes that match URL without a locale in it.

This is ignored if there are no locales configured. It makes no sense to enable this option when match_implicit_locale is disabled.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.