SymfonyWorld Online 2021 Winter Edition December 9 – 10, 2021 100% Online +20 talks and workshops

New in Symfony 5.4: Route Aliasing

Symfony 5.4 is backed by Private Packagist. Private Packagist is a fast, reliable, and secure Composer repository for your private packages. It mirrors all your open-source dependencies for better availability and monitors them for security vulnerabilities.

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.

Help the Symfony project!

As with any Open-Source project, contributing code or documentation is the most common way to help, but we also have a wide range of sponsoring opportunities.

Comments

Nice specifically the deprecated part I remember having a look at 2 years ago when the feature request was opened (but could not get it implemented correctly), and have had a few cases where this would have been useful.

Around route alias' I can figure could be very useful when compiler pass' can edit the destinations. For example homepage being able to be dynamically switched between the different routes based on a variable
Login with SymfonyConnect to post a comment