New in Symfony 5.4: Route Aliasing
Contributed by
Jérôme Parmentier
in #38464.
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_dashboard to admin) but others
are essential for the new application because they change the route name pattern
entirely (e.g. rename api_register_customer_requests_post_collection to
sylius_shop_api_register).
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:
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
# …
The admin route is considered by Symfony the same as admin_dashboard and
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).
Deprecating Routes
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 user_collection_index and
you want to rename it to users_index.
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
deprecated option:
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.“_
Add the message option under deprecated if you want to customize the
deprecation message entirely.
Symfony Blog
Read More