SymfonyWorld Online 2021 Summer Edition
June 17 – 18, 2021
SymfonyWorld Online 2021 Winter Edition
December 9 – 10, 2021
  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 Symfony 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
6
    # app/config/config.yml
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
12
    <!-- 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">
        <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
9
    // app/config/config.php
$container->loadFromExtension('cmf_routing', [
    'chain' => [
        'routers_by_id' => [
            '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 Symfony router will not be overridden by the ChainRouter. By default, the ChainRouter will override the default Symfony router, but it will pass all requests to the default router, because no other routers were set.

  • YAML
    1
2
3
4
    # app/config/config.yml
cmf_routing:
    chain:
        replace_symfony_router: true
  • XML
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
    <!-- 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">
        <cmf-routing>
            <chain replace-symfony-router="true"/>
        </cmf-routing>
    </config>

</container>
  • PHP
    1
2
3
4
5
6
    // app/config/config.php
$container->loadFromExtension('cmf_routing', [
    'chain' => [
        '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

This configuration specifies the controller that is used when the route enhancers define a template but no explicit controller. It accepts any valid Symfony controller reference.

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. Accepts any valid Symfony controller reference.

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
5
    # app/config/config.yml
cmf_routing:
    dynamic:
        controllers_by_type:
            editable:   AppBundle:Cms:editable
  • XML
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
    <!-- 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>
            <controller-by-type type="editable">AppBundle:Cms:editable</controller-by-type>
        </dynamic>
    </config>

</container>
  • PHP
    1
2
3
4
5
6
7
8
    // app/config/config.php
$container->loadFromExtension('cmf_routing', [
    'dynamic' => [
        'controllers_by_type' => [
            'editable' => 'AppBundle:Cms:editable',
        ],
    ],
]);

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 Symfony choose this controller to handle the request.

  • YAML
    1
2
3
4
5
    # app/config/config.yml
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
14
    <!-- 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>
            <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
 8
 9
10
    // app/config/config.php
use Symfony\Cmf\Bundle\ContentBundle\Document\StaticContent;

$container->loadFromExtension('cmf_routing', [
    'dynamic' => [
        'controllers_by_class' => [
            StaticContent::class => '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
5
    # app/config/config.yml
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
    <!-- 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>
            <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
 8
 9
10
    // app/config/config.php
use Symfony\Cmf\Bundle\ContentBundle\Document\StaticContent;

$container->loadFromExtension('cmf_routing', [
    'dynamic' => [
        'templates_by_class' => [
            StaticContent::class => 'CmfContentBundle:StaticContent:index.html.twig',
        ),
    ),
));

route_collection_limit

type: scalar, default: 0

If this value is set to a number bigger than 0, the getRouteCollection() method returns a collection of routes read from the database. The limit serves to prevent huge route lists if you have a large database. Setting the limit to false disables the limit entirely and attempts to return all routes.

persistence

phpcr
  • YAML
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
    # app/config/config.yml
cmf_routing:
    dynamic:
        persistence:
            phpcr:
                enabled:      false
                manager_name: ~
                route_basepaths:
                    - /cms/routes
                    - /cms/simple
                enable_initializer: true
  • XML
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
    <!-- 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"
                    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
    # app/config/config.php
$container->loadFromExtension('cmf_routing', [
    'dynamic' => [
        'persistence' => [
            'phpcr' => [
                'enabled'            => false,
                'manager_name'       => null,
                'route_basepaths'    => [
                    '/cms/routes',
                    '/cms/simple',
                ],
                '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

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.

enable_initializer

type: boolean default: true

The bundle comes with an initializer that creates the necessary nodes for all route_basepaths roots to exist automatically when initializing the repository or loading fixtures. Sometimes this is not what you want, as the created node is of type ‘Generic’ and you might want the document to be a route (for the homepage). Set this to false to disable the initializer when you create your nodes yourself in your own 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.

route_class

type: string default: 'Symfony\Cmf\Bundle\RoutingBundle\Doctrine\Orm\Route'

The route class to use in your application.

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
5
    # app/config/config.yml
cmf_routing:
    dynamic:
        route_filters_by_id:
            app.routing_filter: 100
  • XML
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
    <!-- 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>
            <route-filter-by-id id="app.routing_filter">100</route-filter-by-id>
        </dynamic>
    </config>

</container>
  • PHP
    1
2
3
4
5
6
7
8
    // app/config/config.php
$container->loadFromExtension('cmf_routing', [
    'dynamic' => [
        'route_filters_by_id' => [
            'app.routing_filter' => 100,
        ],
    ],
]);

content_repository_service_id

type: scalar default: null

One way for routes to specify content is by specifying the content ID. The responsible route enhancer asks the content repository specified here for the content. The repository has to implement Symfony\Cmf\Component\Routing\ContentRepositoryInterface.

Note

If PHPCR is enabled, this setting will default to a generic PHPCR content repository that tries to use the content ID as PHPCR path. 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: []

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.