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:

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

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