From a9e3f8be201dd545a679a05e503b2f75117c57f1 Mon Sep 17 00:00:00 2001
From: Mathieu Santostefano <msantostefano@proton.me>
Date: Tue, 25 Feb 2025 10:04:59 +0100
Subject: [PATCH] fix(route-alias): Clarify route aliases examples with
explicit route names
---
routing.rst | 110 ++++++++++++++++++++++++++++++++++++++++++++--------
1 file changed, 93 insertions(+), 17 deletions(-)
diff --git a/routing.rst b/routing.rst
index a41b9bba6a6..d129f198eac 100644
--- a/routing.rst
+++ b/routing.rst
@@ -1338,13 +1338,56 @@ Route Aliasing
Route alias allow you to have multiple name for the same route:
+Let's say you have a route called ``some_route_name``
+
+.. configuration-block::
+
+ .. code-block:: yaml
+
+ # config/routes.yaml
+ some_route_name:
+ path: /some-path
+ controller: App\Controller\SomeController::index
+
+ .. 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="some_route_name" path="/some-path" controller="App\Controller\SomeController::index"/>
+ </routes>
+
+ .. code-block:: php
+
+ // config/routes.php
+ use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
+
+ return static function (RoutingConfigurator $routes): void {
+ $routes->add('some_route_name', '/some-path')
+ ->controller('App\Controller\SomeController::index');
+ };
+
+Now, let's say you want to create a new route called ``new_route_name``
+that acts exactly the same as ``some_route_name``.
+
+Instead of duplicating the original route, you can create an alias for it. You can do this as follows:
+
.. configuration-block::
.. code-block:: yaml
# config/routes.yaml
+ some_route_name:
+ path: /some-path
+ controller: App\Controller\SomeController::index
+
new_route_name:
- alias: original_route_name
+ # "alias" option refers to the name of the route declared above
+ alias: some_route_name
.. code-block:: xml
@@ -1355,7 +1398,9 @@ 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="some_route_name" path="/some-path" controller="App\Controller\SomeController::index"/>
+ <!-- "alias" attribute value refers to the name of the route declared above -->
+ <route id="new_route_name" alias="some_route_name"/>
</routes>
.. code-block:: php
@@ -1364,10 +1409,13 @@ 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('some_route_name', '/some_route_path')
+ ->controller('App\Controller\SomeController::index');
+ // second argument refers to the name of the route declared above
+ $routes->alias('new_route_name', 'some_route_name');
};
-In this example, both ``original_route_name`` and ``new_route_name`` routes can
+In this example, both ``some_route_name`` and ``new_route_name`` routes can
be used in the application and will produce the same result.
.. _routing-alias-deprecation:
@@ -1375,27 +1423,44 @@ be used in the application and will produce the same result.
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 ``some_route_name`` route in favor of
+``new_route_name`` and mark the old one as deprecated.
+
+In the previous example, the alias was ``new_route_name`` was pointing to
+``some_route_name`` route.
+
+As you want to deprecate the ``some_route_name`` route, so let's invert the alias as follows
+to be able to mark it as deprecated using the ``deprecated`` option:
.. configuration-block::
.. code-block:: yaml
+ # Move the concrete route definition under ``new_route_name``
new_route_name:
- alias: original_route_name
+ path: /some-path
+ controller: App\Controller\SomeController::index
+
+ # Define the alias and the deprecation under the ``some_route_name`` definition
+ some_route_name:
+ alias: new_route_name
# 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 "some_route_name" route alias is deprecated. You should stop using it, as it will be removed in the future.
deprecated:
package: 'acme/package'
version: '1.2'
+ # or
+
# you can also 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 "new_route_name" instead.'
.. code-block:: xml
@@ -1405,35 +1470,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 ``new_route_name`` -->
+ <route id="new_route_name" path="/some-path" controller="App\Controller\SomeController::index"/>
+
+ <!-- Define the alias and the deprecation under the ``some_route_name`` definition -->
+ <route id="some_route_name" alias="new_route_name">
<!-- 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 "some_route_name" route alias is deprecated. You should stop using it, as it will be removed in the future. -->
<deprecated package="acme/package" version="1.2"/>
+ <!-- or -->
+
<!-- you can also 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 "new_route_name" instead.
</deprecated>
</route>
</routes>
.. code-block:: php
- $routes->alias('new_route_name', 'original_route_name')
+ $routes->add('new_route_name', '/some-path')
+ ->controller('App\Controller\SomeController::index');
+
+ $routes->alias('some_route_name', 'new_route_name')
// 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 "some_route_name" route alias is deprecated. You should stop using it, as it will be removed in the future.
->deprecate('acme/package', '1.2', '')
+ // or
+
// you can also 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 "new_route_name" 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 ``some_route_name`` alias is used, a deprecation
+warning is triggered, advising you to stop using this route and prefer using ``new_route_name``.
The message is actually a message template, which replaces occurrences of the
``%alias_id%`` placeholder by the route alias name. You **must** have