Skip to content

Commit cfd203d

Browse files
javiereguiluzjaviereguiluz
committed
Tweaks
1 parent ce2a6cd commit cfd203d

File tree

1 file changed

+65
-64
lines changed

1 file changed

+65
-64
lines changed

‎routing.rst

Lines changed: 65 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -1470,110 +1470,111 @@ A possible solution is to change the parameter requirements to be more permissiv
14701470

14711471
.. _routing-alias:
14721472

1473-
Aliasing
1474-
--------
1473+
Route Aliasing
1474+
--------------
14751475

14761476
.. versionadded:: 5.4
14771477

14781478
Support for route aliases was introduced in Symfony 5.4.
14791479

1480-
You may sometimes want to have multiple names for the same route. You can do so by
1481-
aliasing them.
1480+
Route alias allow you to have multiple name for the same route:
14821481

14831482
.. configuration-block::
14841483

14851484
.. code-block:: yaml
14861485
1487-
# config/routes.yaml
1488-
alias_name:
1489-
alias: target_route_name
1486+
# config/routes.yaml
1487+
new_route_name:
1488+
alias: original_route_name
14901489
14911490
.. code-block:: xml
14921491
1493-
<!-- config/routes.xml -->
1494-
<?xml version="1.0" encoding="UTF-8" ?>
1495-
<routes xmlns="http://symfony.com/schema/routing"
1496-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
1497-
xsi:schemaLocation="http://symfony.com/schema/routing
1498-
https://symfony.com/schema/routing/routing-1.0.xsd">
1492+
<!-- config/routes.xml -->
1493+
<?xml version="1.0" encoding="UTF-8" ?>
1494+
<routes xmlns="http://symfony.com/schema/routing"
1495+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
1496+
xsi:schemaLocation="http://symfony.com/schema/routing
1497+
https://symfony.com/schema/routing/routing-1.0.xsd">
14991498
1500-
<route id="alias_name" alias="target_route_name"/>
1501-
</routes>
1499+
<route id="new_route_name" alias="original_route_name"/>
1500+
</routes>
15021501
15031502
.. code-block:: php
15041503
1505-
// config/routes.php
1506-
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
1504+
// config/routes.php
1505+
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
1506+
1507+
return function (RoutingConfigurator $routes) {
1508+
$routes->alias('new_route_name', 'original_route_name');
1509+
};
15071510
1508-
return function (RoutingConfigurator $routes) {
1509-
$routes->alias('alias_name', 'target_route_name');
1510-
};
1511+
In this example, both ``original_route_name`` and ``new_route_name`` routes can
1512+
be used in the application and will produce the same result.
15111513

15121514
.. _routing-alias-deprecation:
15131515

15141516
Deprecating Route Aliases
15151517
~~~~~~~~~~~~~~~~~~~~~~~~~
15161518

1517-
If you decide to deprecate the use of a route alias (because it is outdated or
1519+
If some route alias should no longer be used (because it is outdated or
15181520
you decided not to maintain it anymore), you can deprecate its definition:
15191521

15201522
.. configuration-block::
15211523

15221524
.. code-block:: yaml
15231525
1524-
alias_name:
1525-
alias: target_route_name
1526+
new_route_name:
1527+
alias: original_route_name
15261528
1527-
# this outputs the following generic deprecation message:
1528-
# Since acme/package 1.2: The "alias_name" route alias is deprecated. You should stop using it, as it will be removed in the future.
1529-
deprecated:
1530-
package: 'acme/package'
1531-
version: '1.2'
1529+
# this outputs the following generic deprecation message:
1530+
# 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.
1531+
deprecated:
1532+
package: 'acme/package'
1533+
version: '1.2'
15321534
1533-
# you can also define a custom deprecation message (%alias_id% placeholder is available)
1534-
deprecated:
1535-
package: 'acme/package'
1536-
version: '1.2'
1537-
message: 'The "%alias_id%" route alias is deprecated. Do not use it anymore.'
1535+
# you can also define a custom deprecation message (%alias_id% placeholder is available)
1536+
deprecated:
1537+
package: 'acme/package'
1538+
version: '1.2'
1539+
message: 'The "%alias_id%" route alias is deprecated. Do not use it anymore.'
15381540
15391541
.. code-block:: xml
15401542
1541-
<?xml version="1.0" encoding="UTF-8" ?>
1542-
<routes xmlns="http://symfony.com/schema/routing"
1543-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
1544-
xsi:schemaLocation="http://symfony.com/schema/routing
1545-
https://symfony.com/schema/routing/routing-1.0.xsd">
1543+
<?xml version="1.0" encoding="UTF-8" ?>
1544+
<routes xmlns="http://symfony.com/schema/routing"
1545+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
1546+
xsi:schemaLocation="http://symfony.com/schema/routing
1547+
https://symfony.com/schema/routing/routing-1.0.xsd">
15461548
1547-
<route id="alias_name" alias="target_route_name">
1548-
<!-- this outputs the following generic deprecation message:
1549-
Since acme/package 1.2: The "alias_name" route alias is deprecated. You should stop using it, as it will be removed in the future. -->
1550-
<deprecated package="acme/package" version="1.2"/>
1549+
<route id="new_route_name" alias="original_route_name">
1550+
<!-- this outputs the following generic deprecation message:
1551+
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. -->
1552+
<deprecated package="acme/package" version="1.2"/>
15511553
1552-
<!-- you can also define a custom deprecation message (%alias_id% placeholder is available) -->
1553-
<deprecated package="acme/package" version="1.2">
1554-
The "%alias_id%" route alias is deprecated. Do not use it anymore.
1555-
</deprecated>
1556-
</route>
1557-
</routes>
1554+
<!-- you can also define a custom deprecation message (%alias_id% placeholder is available) -->
1555+
<deprecated package="acme/package" version="1.2">
1556+
The "%alias_id%" route alias is deprecated. Do not use it anymore.
1557+
</deprecated>
1558+
</route>
1559+
</routes>
15581560
15591561
.. code-block:: php
15601562
1561-
$routes->alias('alias_name', 'target_route_name')
1562-
1563-
// this outputs the following generic deprecation message:
1564-
// Since acme/package 1.2: The "alias_name" route alias is deprecated. You should stop using it, as it will be removed in the future.
1565-
->deprecate('acme/package', '1.2', '')
1566-
1567-
// you can also define a custom deprecation message (%alias_id% placeholder is available)
1568-
->deprecate(
1569-
'acme/package',
1570-
'1.2',
1571-
'The "%alias_id%" route alias is deprecated. Do not use it anymore.'
1572-
)
1573-
;
1574-
1575-
Now, every time this route alias is used, a deprecation warning is triggered,
1576-
advising you to stop or to change your uses of that alias.
1563+
$routes->alias('new_route_name', 'original_route_name')
1564+
// this outputs the following generic deprecation message:
1565+
// 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.
1566+
->deprecate('acme/package', '1.2', '')
1567+
1568+
// you can also define a custom deprecation message (%alias_id% placeholder is available)
1569+
->deprecate(
1570+
'acme/package',
1571+
'1.2',
1572+
'The "%alias_id%" route alias is deprecated. Do not use it anymore.'
1573+
)
1574+
;
1575+
1576+
In this example, every time the ``new_route_name`` alias is used, a deprecation
1577+
warning is triggered, advising you to stop using that alias.
15771578

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

0 commit comments

Comments
 (0)