Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

Commit 4b5d780

Browse filesBrowse files
committed
Merge branch '7.2' into 7.3
* 7.2: [Routing] Clarify route aliases examples with explicit route names
2 parents b28aa91 + 24aecee commit 4b5d780
Copy full SHA for 4b5d780

File tree

1 file changed

+100
-23
lines changed
Filter options

1 file changed

+100
-23
lines changed

‎routing.rst

Copy file name to clipboardExpand all lines: routing.rst
+100-23Lines changed: 100 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1334,15 +1334,18 @@ A possible solution is to change the parameter requirements to be more permissiv
13341334
Route Aliasing
13351335
--------------
13361336

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

13391341
.. configuration-block::
13401342

13411343
.. code-block:: yaml
13421344
13431345
# config/routes.yaml
1344-
new_route_name:
1345-
alias: original_route_name
1346+
product_show:
1347+
path: /product/{id}
1348+
controller: App\Controller\ProductController::show
13461349
13471350
.. code-block:: xml
13481351
@@ -1353,7 +1356,7 @@ Route alias allow you to have multiple name for the same route:
13531356
xsi:schemaLocation="http://symfony.com/schema/routing
13541357
https://symfony.com/schema/routing/routing-1.0.xsd">
13551358
1356-
<route id="new_route_name" alias="original_route_name"/>
1359+
<route id="product_show" path="/product/{id}" controller="App\Controller\ProductController::show"/>
13571360
</routes>
13581361
13591362
.. code-block:: php
@@ -1362,38 +1365,101 @@ Route alias allow you to have multiple name for the same route:
13621365
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
13631366
13641367
return static function (RoutingConfigurator $routes): void {
1365-
$routes->alias('new_route_name', 'original_route_name');
1368+
$routes->add('product_show', '/product/{id}')
1369+
->controller('App\Controller\ProductController::show');
13661370
};
13671371
1368-
In this example, both ``original_route_name`` and ``new_route_name`` routes can
1372+
Now, let's say you want to create a new route called ``product_details``
1373+
that acts exactly the same as ``product_show``.
1374+
1375+
Instead of duplicating the original route, you can create an alias for it.
1376+
1377+
.. configuration-block::
1378+
1379+
.. code-block:: yaml
1380+
1381+
# config/routes.yaml
1382+
product_show:
1383+
path: /product/{id}
1384+
controller: App\Controller\ProductController::show
1385+
1386+
product_details:
1387+
# "alias" option refers to the name of the route declared above
1388+
alias: product_show
1389+
1390+
.. code-block:: xml
1391+
1392+
<!-- config/routes.xml -->
1393+
<?xml version="1.0" encoding="UTF-8" ?>
1394+
<routes xmlns="http://symfony.com/schema/routing"
1395+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
1396+
xsi:schemaLocation="http://symfony.com/schema/routing
1397+
https://symfony.com/schema/routing/routing-1.0.xsd">
1398+
1399+
<route id="product_show" path="/product/{id}" controller="App\Controller\ProductController::show"/>
1400+
<!-- "alias" attribute value refers to the name of the route declared above -->
1401+
<route id="product_details" alias="product_show"/>
1402+
</routes>
1403+
1404+
.. code-block:: php
1405+
1406+
// config/routes.php
1407+
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
1408+
1409+
return static function (RoutingConfigurator $routes): void {
1410+
$routes->add('product_show', '/product/{id}')
1411+
->controller('App\Controller\ProductController::show');
1412+
// second argument refers to the name of the route declared above
1413+
$routes->alias('product_details', 'product_show');
1414+
};
1415+
1416+
In this example, both ``product_show`` and ``product_details`` routes can
13691417
be used in the application and will produce the same result.
13701418

13711419
.. _routing-alias-deprecation:
13721420

13731421
Deprecating Route Aliases
13741422
~~~~~~~~~~~~~~~~~~~~~~~~~
13751423

1376-
If some route alias should no longer be used (because it is outdated or
1377-
you decided not to maintain it anymore), you can deprecate its definition:
1424+
Route aliases can be used to provide backward compatibility for routes that
1425+
have been renamed.
1426+
1427+
Now, let's say you want to replace the ``product_show`` route in favor of
1428+
``product_details`` and mark the old one as deprecated.
1429+
1430+
In the previous example, the alias ``product_details`` was pointing to
1431+
``product_show`` route.
1432+
1433+
To mark the ``product_show`` route as deprecated, you need to "switch" the alias.
1434+
The ``product_show`` become the alias, and will now point to the ``product_details`` route.
1435+
This way, the ``product_show`` alias could be deprecated.
13781436

13791437
.. configuration-block::
13801438

13811439
.. code-block:: yaml
13821440
1383-
new_route_name:
1384-
alias: original_route_name
1441+
# Move the concrete route definition under ``product_details``
1442+
product_details:
1443+
path: /product/{id}
1444+
controller: App\Controller\ProductController::show
1445+
1446+
# Define the alias and the deprecation under the ``product_show`` definition
1447+
product_show:
1448+
alias: product_details
13851449
13861450
# this outputs the following generic deprecation message:
1387-
# 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.
1451+
# 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.
13881452
deprecated:
13891453
package: 'acme/package'
13901454
version: '1.2'
13911455
1392-
# you can also define a custom deprecation message (%alias_id% placeholder is available)
1456+
# or
1457+
1458+
# you can define a custom deprecation message (%alias_id% placeholder is available)
13931459
deprecated:
13941460
package: 'acme/package'
13951461
version: '1.2'
1396-
message: 'The "%alias_id%" route alias is deprecated. Do not use it anymore.'
1462+
message: 'The "%alias_id%" route alias is deprecated. Please use "product_details" instead.'
13971463
13981464
.. code-block:: xml
13991465
@@ -1403,35 +1469,46 @@ you decided not to maintain it anymore), you can deprecate its definition:
14031469
xsi:schemaLocation="http://symfony.com/schema/routing
14041470
https://symfony.com/schema/routing/routing-1.0.xsd">
14051471
1406-
<route id="new_route_name" alias="original_route_name">
1472+
<!-- Move the concrete route definition under ``product_details`` -->
1473+
<route id="product_details" path="/product/{id}" controller="App\Controller\ProductController::show"/>
1474+
1475+
<!-- Define the alias and the deprecation under the ``product_show`` definition -->
1476+
<route id="product_show" alias="product_details">
14071477
<!-- this outputs the following generic deprecation message:
1408-
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. -->
1478+
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. -->
14091479
<deprecated package="acme/package" version="1.2"/>
14101480
1411-
<!-- you can also define a custom deprecation message (%alias_id% placeholder is available) -->
1481+
<!-- or -->
1482+
1483+
<!-- you can define a custom deprecation message (%alias_id% placeholder is available) -->
14121484
<deprecated package="acme/package" version="1.2">
1413-
The "%alias_id%" route alias is deprecated. Do not use it anymore.
1485+
The "%alias_id%" route alias is deprecated. Please use "product_details" instead.
14141486
</deprecated>
14151487
</route>
14161488
</routes>
14171489
14181490
.. code-block:: php
14191491
1420-
$routes->alias('new_route_name', 'original_route_name')
1492+
$routes->add('product_details', '/product/{id}')
1493+
->controller('App\Controller\ProductController::show');
1494+
1495+
$routes->alias('product_show', 'product_details')
14211496
// this outputs the following generic deprecation message:
1422-
// 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.
1497+
// 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.
14231498
->deprecate('acme/package', '1.2', '')
14241499
1425-
// you can also define a custom deprecation message (%alias_id% placeholder is available)
1500+
// or
1501+
1502+
// you can define a custom deprecation message (%alias_id% placeholder is available)
14261503
->deprecate(
14271504
'acme/package',
14281505
'1.2',
1429-
'The "%alias_id%" route alias is deprecated. Do not use it anymore.'
1506+
'The "%alias_id%" route alias is deprecated. Please use "product_details" instead.'
14301507
)
14311508
;
14321509
1433-
In this example, every time the ``new_route_name`` alias is used, a deprecation
1434-
warning is triggered, advising you to stop using that alias.
1510+
In this example, every time the ``product_show`` alias is used, a deprecation
1511+
warning is triggered, advising you to stop using this route and prefer using ``product_details``.
14351512

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

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.