Skip to content

[Routing] Document the new alias feature #16074

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 3, 2022
Merged

[Routing] Document the new alias feature #16074

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 111 additions & 0 deletions routing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1453,6 +1453,117 @@ A possible solution is to change the parameter requirements to be more permissiv
as the token and the format will be empty. This can be solved by replacing
the ``.+`` requirement by ``[^.]+`` to allow any character except dots.

.. _routing-alias:

Aliasing
--------

.. versionadded:: 5.4

Support for route aliases was introduced in Symfony 5.4.

You may sometimes want to have multiple names for the same route. You can do so by
aliasing them.

.. configuration-block::

.. code-block:: yaml

# config/routes.yaml
alias_name:
alias: target_route_name

.. 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="alias_name" alias="target_route_name"/>
</routes>

.. code-block:: php

// config/routes.php
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return function (RoutingConfigurator $routes) {
$routes->alias('alias_name', 'target_route_name');
};

.. _routing-alias-deprecation:

Deprecating Route Aliases
~~~~~~~~~~~~~~~~~~~~~~~~~

If you decide to deprecate the use of a route alias (because it is outdated or
you decided not to maintain it anymore), you can deprecate its definition:

.. configuration-block::

.. code-block:: yaml

alias_name:
alias: target_route_name

# this outputs the following generic deprecation message:
# 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.
deprecated:
package: 'acme/package'
version: '1.2'

# 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.'

.. code-block:: 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="alias_name" alias="target_route_name">
<!-- this outputs the following generic deprecation message:
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. -->
<deprecated package="acme/package" version="1.2"/>

<!-- 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.
</deprecated>
</route>
</routes>

.. code-block:: php

$routes->alias('alias_name', 'target_route_name')

// this outputs the following generic deprecation message:
// 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.
->deprecate('acme/package', '1.2', '')

// 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.'
)
;

Now, every time this route alias is used, a deprecation warning is triggered,
advising you to stop or to change your uses of that alias.

The message is actually a message template, which replaces occurrences of the
``%alias_id%`` placeholder by the route alias name. You **must** have
at least one occurrence of the ``%alias_id%`` placeholder in your template.

.. _routing-route-groups:

Route Groups and Prefixes
Expand Down