Skip to content
  • About
    • What is Symfony?
    • Community
    • News
    • Contributing
    • Support
  • Documentation
    • Symfony Docs
    • Symfony Book
    • Screencasts
    • Symfony Bundles
    • Symfony Cloud
    • Training
  • Services
    • Platform.sh for Symfony Best platform to deploy Symfony apps
    • SymfonyInsight Automatic quality checks for your apps
    • Symfony Certification Prove your knowledge and boost your career
    • SensioLabs Professional services to help you with Symfony
    • Blackfire Profile and monitor performance of your apps
  • Other
  • Blog
  • Download
sponsored by
  1. Home
  2. Documentation
  3. Routing
  4. How to Include External Routing Resources
  • Documentation
  • Book
  • Reference
  • Bundles
  • Cloud

Table of Contents

  • 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

Edit this page

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

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

How to Include External Routing Resources

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

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

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

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

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

app_bundle:
    # loads routes from the YAML, XML or PHP files found in some bundle directory
    resource: '@AcmeOtherBundle/Resources/config/routing/'
    type:     directory
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<!-- app/config/routing.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
        https://symfony.com/schema/routing/routing-1.0.xsd">

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

    <!-- loads routes from the PHP annotations of the controllers found in that directory -->
    <import resource="@AppBundle/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="@AcmeOtherBundle/Resources/config/routing/" type="directory"/>
</routes>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// app/config/routing.php
use Symfony\Component\Routing\RouteCollection;

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

    // loads routes from the PHP annotations of the controllers found in that directory
    $loader->import("@AppBundle/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
    $routes->import('@AcmeOtherBundle/Resources/config/routing/public/', 'directory');
};

return $routes;

Note

When importing resources, the key (e.g. app_file) is the name of collection. Just be sure that it's unique per file 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, to prefix all application routes with /site (e.g./site/blog/{slug} instead of /blog/{slug}):

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

/**
 * @Route("/site")
 */
class DefaultController
{
    // ...
}
1
2
3
4
5
# app/config/routing.yml
app:
    resource: '@AppBundle/Controller/'
    type:     annotation
    prefix:   /site
1
2
3
4
5
6
7
8
9
10
11
12
<!-- app/config/routing.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
        https://symfony.com/schema/routing/routing-1.0.xsd">

    <import
        resource="@AppBundle/Controller/"
        type="annotation"
        prefix="/site"/>
</routes>
1
2
3
4
5
6
7
8
9
10
// app/config/routing.php
use Symfony\Component\Routing\RouteCollection;

$app = $loader->import('@AppBundle/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

3.4

The feature to prefix route names was introduced in Symfony 3.4.

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 indexAction()
    {
        // ...
    }

    /**
     * @Route("/blog/posts/{slug}", name="post")
     */
    public function showAction(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.
TOC
    Version
    We stand with Ukraine.
    Version:
    Symfony Code Performance Profiling

    Symfony Code Performance Profiling

    Check Code Performance in Dev, Test, Staging & Production

    Check Code Performance in Dev, Test, Staging & Production

    Symfony footer

    ↓ Our footer now uses the colors of the Ukrainian flag because Symfony stands with the people of Ukraine.

    Avatar of Tomáš Votruba, a Symfony contributor

    Thanks Tomáš Votruba (@tomas_votruba) for being a Symfony contributor

    14 commits • 597 lines changed

    View all contributors that help us make Symfony

    Become a Symfony contributor

    Be an active part of the community and contribute ideas, code and bug fixes. Both experts and newcomers are welcome.

    Learn how to contribute

    Symfony™ is a trademark of Symfony SAS. All rights reserved.

    • What is Symfony?

      • Symfony at a Glance
      • Symfony Components
      • Case Studies
      • Symfony Releases
      • Security Policy
      • Logo & Screenshots
      • Trademark & Licenses
      • symfony1 Legacy
    • Learn Symfony

      • Symfony Docs
      • Symfony Book
      • Reference
      • Bundles
      • Best Practices
      • Training
      • eLearning Platform
      • Certification
    • Screencasts

      • Learn Symfony
      • Learn PHP
      • Learn JavaScript
      • Learn Drupal
      • Learn RESTful APIs
    • Community

      • SymfonyConnect
      • Support
      • How to be Involved
      • Code of Conduct
      • Events & Meetups
      • Projects using Symfony
      • Downloads Stats
      • Contributors
      • Backers
    • Blog

      • Events & Meetups
      • A week of symfony
      • Case studies
      • Cloud
      • Community
      • Conferences
      • Diversity
      • Documentation
      • Living on the edge
      • Releases
      • Security Advisories
      • SymfonyInsight
      • Twig
      • SensioLabs
    • Services

      • SensioLabs services
      • Train developers
      • Manage your project quality
      • Improve your project performance
      • Host Symfony projects

      Deployed on

    Follow Symfony

    Search by Meilisearch