How to Include External Routing Resources

Warning: You are browsing the documentation for Symfony 4.0, which is no longer maintained.

Read the updated version of this page for Symfony 6.2 (the current stable version).

Prefixing the URLs of Imported Routes
Prefixing the Names of Imported Routes
Adding a Host Requirement to Imported Routes

How to Include External Routing Resources

Simple applications can define all their routes in a single configuration file - usually config/routes.yaml (see Routing). However, in most applications it's common to import routes definitions from different resources: PHP annotations in controller files, YAML or XML files stored in some directory, etc.

This can be done by importing routing resources from the main routing file:

YAML
XML
PHP

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
        # config/routes.yaml
app_file:
    # loads routes from the given routing file stored in some bundle
    resource: '@AcmeOtherBundle/Resources/config/routing.yml'

app_annotations:
    # loads routes from the PHP annotations of the controllers found in that directory
    resource: '../src/Controller/'
    type:     annotation

app_directory:
    # loads routes from the YAML or XML files found in that directory
    resource: '../legacy/routing/'
    type:     directory

app_bundle:
    # loads routes from the YAML or XML files found in some bundle directory
    resource: '@AppBundle/Resources/config/routing/public/'
    type:     directory
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
        <!-- 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">

    <!-- loads routes from the given routing file stored in some bundle -->
    <import resource="@AcmeOtherBundle/Resources/config/routing.yml" />

    <!-- loads routes from the PHP annotations of the controllers found in that directory -->
    <import resource="../src/Controller/" type="annotation" />

    <!-- loads routes from the YAML or XML files found in that directory -->
    <import resource="../legacy/routing/" type="directory" />

    <!-- loads routes from the YAML or XML files found in some bundle directory -->
    <import resource="@AppBundle/Resources/config/routing/public/" type="directory" />
</routes>
    

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
        // config/routes.php
use Symfony\Component\Routing\RouteCollection;

$routes = new RouteCollection();
$routes->addCollection(
    // loads routes from the given routing file stored in some bundle
    $loader->import("@AcmeOtherBundle/Resources/config/routing.yml")

    // loads routes from the PHP annotations of the controllers found in that directory
    $loader->import("../src/Controller/", "annotation")

    // loads routes from the YAML or XML files found in that directory
    $loader->import("../legacy/routing/", "directory")

    // loads routes from the YAML or XML files found in some bundle directory
    $loader->import("@AppBundle/Resources/config/routing/public/", "directory")
);

return $routes;
    

Note

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

Prefixing the URLs of 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}):

Annotations
YAML
XML
PHP

        1
2
3
4
5
6
7
8
9
        use Symfony\Component\Routing\Annotation\Route;

/**
 * @Route("/site")
 */
class DefaultController
{
    // ...
}
    

        1
2
3
4
5
        # config/routes.yaml
controllers:
    resource: '../src/Controller/'
    type:     annotation
    prefix:   /site
    

        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>
    

        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');

$routes = new RouteCollection();
$routes->addCollection($app);

return $routes;
    

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

Prefixing the Names of Imported Routes

You also have the possibility to prefix all route names defined in a controller class with the name attribute of the @Route annotation:

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
        use Symfony\Component\Routing\Annotation\Route;

/**
 * @Route(name="blog_")
 */
class BlogController extends Controller
{
    /**
     * @Route("/blog", name="index")
     */
    public function index()
    {
        // ...
    }

    /**
     * @Route("/blog/posts/{slug}", name="post")
     */
    public function show(Post $post)
    {
        // ...
    }
}
    

In this example, the names of the routes will be blog_index and blog_post.

Adding a Host Requirement to Imported Routes

You can set the host regex on imported routes. For more information, see How to Match a Route Based on the Host.

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

How to Include External Routing Resources

How to Include External Routing Resources

Prefixing the URLs of Imported Routes

Prefixing the Names of Imported Routes

Adding a Host Requirement to Imported Routes

What is Symfony?

Learn Symfony

Screencasts

Community

Blog

Services

Deployed on