How to Include External Routing Resources
Edit this pageWarning: You are browsing the documentation for Symfony 4.1, which is no longer maintained.
Read the updated version of this page for Symfony 6.1 (the current stable version).
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
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
{
// ...
}
The path of each route being loaded from the new routing resource will now
be prefixed with the string /site
.
Note
If any of the prefixed routes defines an empty path, Symfony adds a trailing
slash to it. In the previous example, an empty path prefixed with /site
will result in the /site/
URL. If you want to avoid this behavior, set
the trailing_slash_on_root
option to false
:
- YAML
- XML
- PHP
1 2 3 4 5 6
# config/routes.yaml
controllers:
resource: '../src/Controller/'
type: annotation
prefix: /site
trailing_slash_on_root: false
4.1
The trailing_slash_on_root
option was introduced in Symfony 4.1.
Prefixing the Names of Imported Routes
You also have the possibility to prefix the names of all the routes defined in a controller class or imported from a configuration file:
- Annotations
- YAML
- XML
- PHP
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 AbstractController
{
/**
* @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
.
4.1
The option to prefix route names in YAML, XML and PHP files was introduced
in Symfony 4.1. Previously only the @Route()
annotation supported this
feature.
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.