New in Symfony 5.4: Route Aliasing
When refactoring applications, especially if you work on a legacy application,
it's common to need to change the name of some routes. Some renames might be
considered cosmetic (e.g. rename
admin) but others
are essential for the new application because they change the route name pattern
entirely (e.g. rename
The need to rename routes is increasingly popular among Symfony developers and
that's why in Symfony 5.4, we're improving the Routing component to allow
aliasing routes. In any route configuration, add the
alias option and
provide the name of the route which is equivalent to it. For example:
1 2 3 4 5 6 7 8 9
# config/routes.yaml # this is the existing and 'legacy' route admin_dashboard: # ... # this is the new route that replaces the old one admin: alias: admin_dashboard # ...
admin route is considered by Symfony the same as
you can generate the same URLs with both of them. The above example uses YAML,
but it works with all the other route configuration formats as well (PHP, XML).
An added bonus of this feature is that you can deprecate routes and tell users
in advance so they can update their applications. Imagine that you publish a
third-party bundle that includes a route called
you want to rename it to
Instead of just renaming the route (which would break all applications using the
bundle) define the old route as an alias of the new route and add to it the
1 2 3 4 5 6 7 8 9 10
# config/routes.yaml users_index: # ... user_collection_index: alias: 'users_index' deprecated: package: 'some-vendor/some-package' version: '3.14' # ...
If any application uses the
user_collection_index route to generate URLs,
they'll see the following deprecation message: "Since some-vendor/some-package 3.14:
The "user_collection_index" route alias is deprecated. You should stop using it,
as it will be removed in the future."
message option under
deprecated if you want to customize the
deprecation message entirely.