Skip to content

Commit 194ca17

Browse files
committed
[Routing] Document the new alias feature
1 parent 69992ab commit 194ca17

File tree

1 file changed

+111
-0
lines changed

1 file changed

+111
-0
lines changed

routing.rst

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1453,6 +1453,117 @@ A possible solution is to change the parameter requirements to be more permissiv
14531453
as the token and the format will be empty. This can be solved by replacing
14541454
the ``.+`` requirement by ``[^.]+`` to allow any character except dots.
14551455

1456+
.. _routing-alias:
1457+
1458+
Aliasing
1459+
--------
1460+
1461+
.. versionadded:: 5.4
1462+
1463+
Support for route aliases was introduced in Symfony 5.4.
1464+
1465+
You may sometimes want to have multiple names for the same route. You can do so by
1466+
aliasing them.
1467+
1468+
.. configuration-block::
1469+
1470+
.. code-block:: yaml
1471+
1472+
# config/routes.yaml
1473+
alias_name:
1474+
alias: target_route_name
1475+
1476+
.. code-block:: xml
1477+
1478+
<!-- config/routes.xml -->
1479+
<?xml version="1.0" encoding="UTF-8" ?>
1480+
<routes xmlns="http://symfony.com/schema/routing"
1481+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
1482+
xsi:schemaLocation="http://symfony.com/schema/routing
1483+
https://symfony.com/schema/routing/routing-1.0.xsd">
1484+
1485+
<route id="alias_name" alias="target_route_name"/>
1486+
</routes>
1487+
1488+
.. code-block:: php
1489+
1490+
// config/routes.php
1491+
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
1492+
1493+
return function (RoutingConfigurator $routes) {
1494+
$routes->alias('alias_name', 'target_route_name');
1495+
};
1496+
1497+
.. _routing-alias-deprecation:
1498+
1499+
Deprecating Route Aliases
1500+
~~~~~~~~~~~~~~~~~~~~~~~~~
1501+
1502+
If you decide to deprecate the use of a route alias (because it is outdated or
1503+
you decided not to maintain it anymore), you can deprecate its definition:
1504+
1505+
.. configuration-block::
1506+
1507+
.. code-block:: yaml
1508+
1509+
alias_name:
1510+
alias: target_route_name
1511+
1512+
# this outputs the following generic deprecation message:
1513+
# 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.
1514+
deprecated:
1515+
package: 'acme/package'
1516+
version: '1.2'
1517+
1518+
# you can also define a custom deprecation message (%alias_id% placeholder is available)
1519+
deprecated:
1520+
package: 'acme/package'
1521+
version: '1.2'
1522+
message: 'The "%alias_id%" route alias is deprecated. Do not use it anymore.'
1523+
1524+
.. code-block:: xml
1525+
1526+
<?xml version="1.0" encoding="UTF-8" ?>
1527+
<routes xmlns="http://symfony.com/schema/routing"
1528+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
1529+
xsi:schemaLocation="http://symfony.com/schema/routing
1530+
https://symfony.com/schema/routing/routing-1.0.xsd">
1531+
1532+
<route id="alias_name" alias="target_route_name">
1533+
<!-- this outputs the following generic deprecation message:
1534+
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. -->
1535+
<deprecated package="acme/package" version="1.2"/>
1536+
1537+
<!-- you can also define a custom deprecation message (%alias_id% placeholder is available) -->
1538+
<deprecated package="acme/package" version="1.2">
1539+
The "%alias_id%" route alias is deprecated. Do not use it anymore.
1540+
</deprecated>
1541+
</route>
1542+
</routes>
1543+
1544+
.. code-block:: php
1545+
1546+
$routes->alias('alias_name', 'target_route_name')
1547+
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+
->deprecate('acme/package', '1.2', '')
1551+
1552+
// you can also define a custom deprecation message (%alias_id% placeholder is available)
1553+
->deprecate(
1554+
'acme/package',
1555+
'1.2',
1556+
'The "%alias_id%" route alias is deprecated. Do not use it anymore.'
1557+
)
1558+
;
1559+
1560+
Now, every time this route alias is used, a deprecation warning is triggered,
1561+
advising you to stop or to change your uses of that alias.
1562+
1563+
The message is actually a message template, which replaces occurrences of the
1564+
``%alias_id%`` placeholder by the route alias name. You **must** have
1565+
at least one occurrence of the ``%alias_id%`` placeholder in your template.
1566+
14561567
.. _routing-route-groups:
14571568

14581569
Route Groups and Prefixes

0 commit comments

Comments
 (0)