Skip to content

[Routing] Clarify route aliases examples with explicit route names #20688

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: 6.4
Choose a base branch
from
Open

[Routing] Clarify route aliases examples with explicit route names #20688

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
34b59df
fix(route-alias): Clarify route aliases examples with explicit route …
welcoMattic Feb 25, 2025
35bff3a
fix(routing): Rename Route Alias route examples
welcoMattic May 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 101 additions & 23 deletions routing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1336,15 +1336,19 @@ A possible solution is to change the parameter requirements to be more permissiv
Route Aliasing
--------------

Route alias allow you to have multiple name for the same route:
Route alias allows you to have multiple name for the same route
and can be used to provide backward compatibility for routes that
have been renamed.
Let's say you have a route called ``product_show``

.. configuration-block::

.. code-block:: yaml

# config/routes.yaml
new_route_name:
alias: original_route_name
product_show:
path: /product/{id}
controller: App\Controller\ProductController::show

.. code-block:: xml

Expand All @@ -1355,7 +1359,7 @@ Route alias allow you to have multiple name for the same route:
xsi:schemaLocation="http://symfony.com/schema/routing
https://symfony.com/schema/routing/routing-1.0.xsd">

<route id="new_route_name" alias="original_route_name"/>
<route id="product_show" path="/product/{id}" controller="App\Controller\ProductController::show"/>
</routes>

.. code-block:: php
Expand All @@ -1364,38 +1368,101 @@ Route alias allow you to have multiple name for the same route:
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return static function (RoutingConfigurator $routes): void {
$routes->alias('new_route_name', 'original_route_name');
$routes->add('product_show', '/product/{id}')
->controller('App\Controller\ProductController::show');
};

In this example, both ``original_route_name`` and ``new_route_name`` routes can
Now, let's say you want to create a new route called ``product_details``
that acts exactly the same as ``product_show``.

Instead of duplicating the original route, you can create an alias for it.

.. configuration-block::

.. code-block:: yaml

# config/routes.yaml
product_show:
path: /product/{id}
controller: App\Controller\ProductController::show

product_details:
# "alias" option refers to the name of the route declared above
alias: product_show

.. code-block:: xml

<!-- config/routes.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<routes xmlns="http://symfony.com/schema/routing"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/routing
https://symfony.com/schema/routing/routing-1.0.xsd">

<route id="product_show" path="/product/{id}" controller="App\Controller\ProductController::show"/>
<!-- "alias" attribute value refers to the name of the route declared above -->
<route id="product_details" alias="product_show"/>
</routes>

.. code-block:: php

// config/routes.php
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return static function (RoutingConfigurator $routes): void {
$routes->add('product_show', '/product/{id}')
->controller('App\Controller\ProductController::show');
// second argument refers to the name of the route declared above
$routes->alias('product_details', 'product_show');
};

In this example, both ``product_show`` and ``product_details`` routes can
be used in the application and will produce the same result.

.. _routing-alias-deprecation:

Deprecating Route Aliases
~~~~~~~~~~~~~~~~~~~~~~~~~

If some route alias should no longer be used (because it is outdated or
you decided not to maintain it anymore), you can deprecate its definition:
Route aliases can be used to provide backward compatibility for routes that
have been renamed.

Now, let's say you want to replace the ``product_show`` route in favor of
``product_details`` and mark the old one as deprecated.

In the previous example, the alias ``product_details`` was pointing to
``product_show`` route.

To mark the ``product_show`` route as deprecated, you need to "switch" the alias.
The ``product_show`` become the alias, and will now point to the ``product_details`` route.
This way, the ``product_show`` alias could be deprecated.

.. configuration-block::

.. code-block:: yaml

new_route_name:
alias: original_route_name
# Move the concrete route definition under ``product_details``
product_details:
path: /product/{id}
controller: App\Controller\ProductController::show

# Define the alias and the deprecation under the ``product_show`` definition
product_show:
alias: product_details

# this outputs the following generic deprecation message:
# Since acme/package 1.2: The "new_route_name" route alias is deprecated. You should stop using it, as it will be removed in the future.
# Since acme/package 1.2: The "product_show" route alias is deprecated. You should stop using it, as it will be removed in the future.
deprecated:
package: 'acme/package'
version: '1.2'

# you can also define a custom deprecation message (%alias_id% placeholder is available)
# or

# you can define a custom deprecation message (%alias_id% placeholder is available)
deprecated:
package: 'acme/package'
version: '1.2'
message: 'The "%alias_id%" route alias is deprecated. Do not use it anymore.'
message: 'The "%alias_id%" route alias is deprecated. Please use "product_details" instead.'

.. code-block:: xml

Expand All @@ -1405,35 +1472,46 @@ you decided not to maintain it anymore), you can deprecate its definition:
xsi:schemaLocation="http://symfony.com/schema/routing
https://symfony.com/schema/routing/routing-1.0.xsd">

<route id="new_route_name" alias="original_route_name">
<!-- Move the concrete route definition under ``product_details`` -->
<route id="product_details" path="/product/{id}" controller="App\Controller\ProductController::show"/>

<!-- Define the alias and the deprecation under the ``product_show`` definition -->
<route id="product_show" alias="product_details">
<!-- this outputs the following generic deprecation message:
Since acme/package 1.2: The "new_route_name" route alias is deprecated. You should stop using it, as it will be removed in the future. -->
Since acme/package 1.2: The "product_show" route alias is deprecated. You should stop using it, as it will be removed in the future. -->
<deprecated package="acme/package" version="1.2"/>

<!-- you can also define a custom deprecation message (%alias_id% placeholder is available) -->
<!-- or -->

<!-- you can define a custom deprecation message (%alias_id% placeholder is available) -->
<deprecated package="acme/package" version="1.2">
The "%alias_id%" route alias is deprecated. Do not use it anymore.
The "%alias_id%" route alias is deprecated. Please use "product_details" instead.
</deprecated>
</route>
</routes>

.. code-block:: php

$routes->alias('new_route_name', 'original_route_name')
$routes->add('product_details', '/product/{id}')
->controller('App\Controller\ProductController::show');

$routes->alias('product_show', 'product_details')
// this outputs the following generic deprecation message:
// Since acme/package 1.2: The "new_route_name" route alias is deprecated. You should stop using it, as it will be removed in the future.
// Since acme/package 1.2: The "product_show" route alias is deprecated. You should stop using it, as it will be removed in the future.
->deprecate('acme/package', '1.2', '')

// you can also define a custom deprecation message (%alias_id% placeholder is available)
// or

// you can define a custom deprecation message (%alias_id% placeholder is available)
->deprecate(
'acme/package',
'1.2',
'The "%alias_id%" route alias is deprecated. Do not use it anymore.'
'The "%alias_id%" route alias is deprecated. Please use "product_details" instead.'
)
;

In this example, every time the ``new_route_name`` alias is used, a deprecation
warning is triggered, advising you to stop using that alias.
In this example, every time the ``product_show`` alias is used, a deprecation
warning is triggered, advising you to stop using this route and prefer using ``product_details``.

The message is actually a message template, which replaces occurrences of the
``%alias_id%`` placeholder by the route alias name. You **must** have
Expand Down