Jérôme Parmentier
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:

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
    # ...

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:

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."

Add the message option under deprecated if you want to customize the deprecation message entirely.

Published in #Living on the edge