Symfony 4 was released on November 30th.
Update now to the best Symfony ever!

You are browsing the Symfony 4 documentation, which changes significantly from Symfony 3.x. If your app doesn't use Symfony 4 yet, browse the Symfony 3.4 documentation.

How to Include External Routing Resources

How to Include External Routing Resources

All routes are loaded via a single configuration file - usually config/routes.yaml (see Creating Routes). However, if you use routing annotations, you'll need to point the router to the controllers with the annotations. This can be done by "importing" directories into the routing configuration:

  • YAML
    1
    2
    3
    4
    # config/routes.yaml
    controllers:
        resource: ../src/Controller/
        type: annotation
    
  • XML
    1
    2
    3
    4
    5
    6
    7
    8
    9
    <!-- config/routes.xml -->
    <?xml version="1.0" encoding="UTF-8" ?>
    <routes xmlns="http://symfony.com/schema/routing"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://symfony.com/schema/routing
            http://symfony.com/schema/routing/routing-1.0.xsd">
    
        <import resource="../src/Controller/" type="annotation"/>
    </routes>
    
  • PHP
    1
    2
    3
    4
    5
    6
    7
    8
    9
    // config/routes.php
    use Symfony\Component\Routing\RouteCollection;
    
    $collection = new RouteCollection();
    $collection->addCollection(
        $loader->import("../src/Controller/", "annotation")
    );
    
    return $collection;
    

Note

When importing resources from YAML, the key (e.g. controllers) is meaningless. Just be sure that it's unique so no other lines override it.

The resource key loads the given routing resource. In this example the resource is a directory and all files in that directory are parsed and put into the routing.

Note

You can also include other routing configuration files:

  • YAML
    1
    2
    3
    # config/routes.yaml
    app:
        resource: '@ThirdPartyBundle/Resources/config/routing.yaml'
    
  • XML
    1
    2
    3
    4
    5
    6
    7
    8
    9
    <!-- config/routes.xml -->
    <?xml version="1.0" encoding="UTF-8" ?>
    <routes xmlns="http://symfony.com/schema/routing"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://symfony.com/schema/routing
            http://symfony.com/schema/routing/routing-1.0.xsd">
    
        <import resource="@ThirdPartyBundle/Resources/config/routing.xml" />
    </routes>
    
  • PHP
    1
    2
    3
    4
    5
    6
    7
    8
    9
    // config/routes.php
    use Symfony\Component\Routing\RouteCollection;
    
    $collection = new RouteCollection();
    $collection->addCollection(
        $loader->import("@ThirdPartyBundle/Resources/config/routing.php")
    );
    
    return $collection;
    

Prefixing Imported Routes

You can also choose to provide a "prefix" for the imported routes. For example, suppose you want to prefix all application routes with /site (e.g. /site/blog/{slug} instead of /blog/{slug}):

  • YAML
    1
    2
    3
    4
    5
    # config/routes.yaml
    controllers:
        resource: '../src/Controller/'
        type:     annotation
        prefix:   /site
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    <!-- config/routes.xml -->
    <?xml version="1.0" encoding="UTF-8" ?>
    <routes xmlns="http://symfony.com/schema/routing"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://symfony.com/schema/routing
            http://symfony.com/schema/routing/routing-1.0.xsd">
    
        <import
            resource="../src/Controller/"
            type="annotation"
            prefix="/site" />
    </routes>
    
  • PHP
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    // config/routes.php
    use Symfony\Component\Routing\RouteCollection;
    
    $app = $loader->import('../src/Controller/', 'annotation');
    $app->addPrefix('/site');
    
    $collection = new RouteCollection();
    $collection->addCollection($app);
    
    return $collection;
    

The path of each route being loaded from the new routing resource will now be prefixed with the string /site.

Adding a Host Requirement to Imported Routes

You can set the host regex on imported routes. For more information, see Using Host Matching of Imported Routes.

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