Movatterモバイル変換

[0]ホーム
URL:

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

 Sign up
Appearance settings

Commit6556d97

Browse files
committed
feature#20688 [Routing] Clarify route aliases examples with explicit route names (welcoMattic)
This PR was squashed before being merged into the 6.4 branch.Discussion----------[Routing] Clarify route aliases examples with explicit route namesRefers to#20638 (comment)Actual examples for route aliasing are not crystal clear.Now, examples in YAML, XML and PHP provide- An original route, declared with an explicit name- An alias to this route, with an explicit nameThis change will allow to provide another clear example for route aliasing using Attribute in#20638cc `@stof` `@damienfern`Commits-------a28b614 [Routing] Clarify route aliases examples with explicit route names
2 parentsaafade6 +a28b614 commit6556d97

File tree

1 file changed

+100
-23
lines changed

1 file changed

+100
-23
lines changed

‎routing.rst

Lines changed: 100 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1337,15 +1337,18 @@ A possible solution is to change the parameter requirements to be more permissiv
13371337
Route Aliasing
13381338
--------------
13391339

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

13421344
..configuration-block::
13431345

13441346
..code-block::yaml
13451347
13461348
# config/routes.yaml
1347-
new_route_name:
1348-
alias:original_route_name
1349+
product_show:
1350+
path:/product/{id}
1351+
controller:App\Controller\ProductController::show
13491352
13501353
..code-block::xml
13511354
@@ -1356,7 +1359,7 @@ Route alias allow you to have multiple name for the same route:
13561359
xsi:schemaLocation="http://symfony.com/schema/routing
13571360
https://symfony.com/schema/routing/routing-1.0.xsd">
13581361
1359-
<routeid="new_route_name"alias="original_route_name"/>
1362+
<routeid="product_show"path="/product/{id}"controller="App\Controller\ProductController::show"/>
13601363
</routes>
13611364
13621365
..code-block::php
@@ -1365,38 +1368,101 @@ Route alias allow you to have multiple name for the same route:
13651368
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
13661369
13671370
return static function (RoutingConfigurator $routes): void {
1368-
$routes->alias('new_route_name', 'original_route_name');
1371+
$routes->add('product_show', '/product/{id}')
1372+
->controller('App\Controller\ProductController::show');
13691373
};
13701374
1371-
In this example, both ``original_route_name`` and ``new_route_name`` routes can
1375+
Now, let's say you want to create a new route called ``product_details``
1376+
that acts exactly the same as ``product_show``.
1377+
1378+
Instead of duplicating the original route, you can create an alias for it.
1379+
1380+
..configuration-block::
1381+
1382+
..code-block::yaml
1383+
1384+
# config/routes.yaml
1385+
product_show:
1386+
path:/product/{id}
1387+
controller:App\Controller\ProductController::show
1388+
1389+
product_details:
1390+
# "alias" option refers to the name of the route declared above
1391+
alias:product_show
1392+
1393+
..code-block::xml
1394+
1395+
<!-- config/routes.xml-->
1396+
<?xml version="1.0" encoding="UTF-8" ?>
1397+
<routesxmlns="http://symfony.com/schema/routing"
1398+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
1399+
xsi:schemaLocation="http://symfony.com/schema/routing
1400+
https://symfony.com/schema/routing/routing-1.0.xsd">
1401+
1402+
<routeid="product_show"path="/product/{id}"controller="App\Controller\ProductController::show"/>
1403+
<!-- "alias" attribute value refers to the name of the route declared above-->
1404+
<routeid="product_details"alias="product_show"/>
1405+
</routes>
1406+
1407+
..code-block::php
1408+
1409+
// config/routes.php
1410+
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
1411+
1412+
return static function (RoutingConfigurator $routes): void {
1413+
$routes->add('product_show', '/product/{id}')
1414+
->controller('App\Controller\ProductController::show');
1415+
// second argument refers to the name of the route declared above
1416+
$routes->alias('product_details', 'product_show');
1417+
};
1418+
1419+
In this example, both ``product_show`` and ``product_details`` routes can
13721420
be used in the application and will produce the same result.
13731421

13741422
.. _routing-alias-deprecation:
13751423

13761424
Deprecating Route Aliases
13771425
~~~~~~~~~~~~~~~~~~~~~~~~~
13781426

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

13821440
..configuration-block::
13831441

13841442
..code-block::yaml
13851443
1386-
new_route_name:
1387-
alias:original_route_name
1444+
# Move the concrete route definition under ``product_details``
1445+
product_details:
1446+
path:/product/{id}
1447+
controller:App\Controller\ProductController::show
1448+
1449+
# Define the alias and the deprecation under the ``product_show`` definition
1450+
product_show:
1451+
alias:product_details
13881452
13891453
# this outputs the following generic deprecation message:
1390-
# 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.
1454+
# 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.
13911455
deprecated:
13921456
package:'acme/package'
13931457
version:'1.2'
13941458
1395-
# you can also define a custom deprecation message (%alias_id% placeholder is available)
1459+
# or
1460+
1461+
# you can define a custom deprecation message (%alias_id% placeholder is available)
13961462
deprecated:
13971463
package:'acme/package'
13981464
version:'1.2'
1399-
message:'The "%alias_id%" route alias is deprecated.Do notuseit anymore.'
1465+
message:'The "%alias_id%" route alias is deprecated.Pleaseuse"product_details" instead.'
14001466
14011467
..code-block::xml
14021468
@@ -1406,35 +1472,46 @@ you decided not to maintain it anymore), you can deprecate its definition:
14061472
xsi:schemaLocation="http://symfony.com/schema/routing
14071473
https://symfony.com/schema/routing/routing-1.0.xsd">
14081474
1409-
<routeid="new_route_name"alias="original_route_name">
1475+
<!-- Move the concrete route definition under ``product_details``-->
1476+
<routeid="product_details"path="/product/{id}"controller="App\Controller\ProductController::show"/>
1477+
1478+
<!-- Define the alias and the deprecation under the ``product_show`` definition-->
1479+
<routeid="product_show"alias="product_details">
14101480
<!-- this outputs the following generic deprecation message:
1411-
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.-->
1481+
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.-->
14121482
<deprecatedpackage="acme/package"version="1.2"/>
14131483
1414-
<!-- you can also define a custom deprecation message (%alias_id% placeholder is available)-->
1484+
<!-- or-->
1485+
1486+
<!-- you can define a custom deprecation message (%alias_id% placeholder is available)-->
14151487
<deprecatedpackage="acme/package"version="1.2">
1416-
The "%alias_id%" route alias is deprecated.Do notuseit anymore.
1488+
The "%alias_id%" route alias is deprecated.Pleaseuse"product_details" instead.
14171489
</deprecated>
14181490
</route>
14191491
</routes>
14201492
14211493
..code-block::php
14221494
1423-
$routes->alias('new_route_name', 'original_route_name')
1495+
$routes->add('product_details', '/product/{id}')
1496+
->controller('App\Controller\ProductController::show');
1497+
1498+
$routes->alias('product_show', 'product_details')
14241499
// this outputs the following generic deprecation message:
1425-
// 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.
1500+
// 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.
14261501
->deprecate('acme/package', '1.2', '')
14271502
1428-
// you can also define a custom deprecation message (%alias_id% placeholder is available)
1503+
// or
1504+
1505+
// you can define a custom deprecation message (%alias_id% placeholder is available)
14291506
->deprecate(
14301507
'acme/package',
14311508
'1.2',
1432-
'The "%alias_id%" route alias is deprecated.Do notuseit anymore.'
1509+
'The "%alias_id%" route alias is deprecated.Pleaseuse"product_details" instead.'
14331510
)
14341511
;
14351512
1436-
In this example, every time the ``new_route_name`` alias is used, a deprecation
1437-
warning is triggered, advising you to stop usingthat alias.
1513+
In this example, every time the ``product_show`` alias is used, a deprecation
1514+
warning is triggered, advising you to stop usingthis route and prefer using ``product_details``.
14381515

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

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp