Skip to content

[Routing] Clarify route aliases examples with explicit route names #20688

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

Open
wants to merge 1 commit into
base: 6.4
Choose a base branch
from
Open

[Routing] Clarify route aliases examples with explicit route names #20688

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
110 changes: 93 additions & 17 deletions routing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1338,13 +1338,56 @@ Route Aliasing

Route alias allow you to have multiple name for the same route:

Let's say you have a route called ``some_route_name``

.. configuration-block::

.. code-block:: yaml

# config/routes.yaml
some_route_name:
path: /some-path
controller: App\Controller\SomeController::index

.. 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="some_route_name" path="/some-path" controller="App\Controller\SomeController::index"/>
</routes>

.. code-block:: php

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

return static function (RoutingConfigurator $routes): void {
$routes->add('some_route_name', '/some-path')
->controller('App\Controller\SomeController::index');
};

Now, let's say you want to create a new route called ``new_route_name``
that acts exactly the same as ``some_route_name``.

Instead of duplicating the original route, you can create an alias for it. You can do this as follows:

.. configuration-block::

.. code-block:: yaml

# config/routes.yaml
some_route_name:
path: /some-path
controller: App\Controller\SomeController::index

new_route_name:
alias: original_route_name
# "alias" option refers to the name of the route declared above
alias: some_route_name

.. code-block:: xml

Expand All @@ -1355,7 +1398,9 @@ Route alias allow you to have multiple name for the same route:
xsi:schemaLocation="http://symfony.com/schema/routing
https://symfony.com/schema/routing/routing-1.0.xsd">

<route id="new_route_name" alias="original_route_name"/>
<route id="some_route_name" path="/some-path" controller="App\Controller\SomeController::index"/>
<!-- "alias" attribute value refers to the name of the route declared above -->
<route id="new_route_name" alias="some_route_name"/>
</routes>

.. code-block:: php
Expand All @@ -1364,38 +1409,58 @@ Route alias allow you to have multiple name for the same route:
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return static function (RoutingConfigurator $routes): void {
$routes->alias('new_route_name', 'original_route_name');
$routes->add('some_route_name', '/some_route_path')
->controller('App\Controller\SomeController::index');
// second argument refers to the name of the route declared above
$routes->alias('new_route_name', 'some_route_name');
};

In this example, both ``original_route_name`` and ``new_route_name`` routes can
In this example, both ``some_route_name`` and ``new_route_name`` routes can
be used in the application and will produce the same result.

.. _routing-alias-deprecation:

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

If some route alias should no longer be used (because it is outdated or
you decided not to maintain it anymore), you can deprecate its definition:
Route aliases can be used to provide backward compatibility for routes that
have been renamed.

Now, let's say you want to replace the ``some_route_name`` route in favor of
``new_route_name`` and mark the old one as deprecated.

In the previous example, the alias was ``new_route_name`` was pointing to
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
In the previous example, the alias was ``new_route_name`` was pointing to
In the previous example, the alias ``new_route_name`` was pointing to

``some_route_name`` route.

As you want to deprecate the ``some_route_name`` route, so let's invert the alias as follows
to be able to mark it as deprecated using the ``deprecated`` option:

.. configuration-block::

.. code-block:: yaml

# Move the concrete route definition under ``new_route_name``
new_route_name:
alias: original_route_name
path: /some-path
controller: App\Controller\SomeController::index

# Define the alias and the deprecation under the ``some_route_name`` definition
some_route_name:
alias: new_route_name

# this outputs the following generic deprecation message:
# 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.
# Since acme/package 1.2: The "some_route_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'

# or

# 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.'
message: 'The "%alias_id%" route alias is deprecated. Please use "new_route_name" instead.'

.. code-block:: xml

Expand All @@ -1405,35 +1470,46 @@ you decided not to maintain it anymore), you can deprecate its definition:
xsi:schemaLocation="http://symfony.com/schema/routing
https://symfony.com/schema/routing/routing-1.0.xsd">

<route id="new_route_name" alias="original_route_name">
<!-- Move the concrete route definition under ``new_route_name`` -->
<route id="new_route_name" path="/some-path" controller="App\Controller\SomeController::index"/>

<!-- Define the alias and the deprecation under the ``some_route_name`` definition -->
<route id="some_route_name" alias="new_route_name">
<!-- this outputs the following generic deprecation message:
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. -->
Since acme/package 1.2: The "some_route_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"/>

<!-- or -->

<!-- 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.
The "%alias_id%" route alias is deprecated. Please use "new_route_name" instead.
</deprecated>
</route>
</routes>

.. code-block:: php

$routes->alias('new_route_name', 'original_route_name')
$routes->add('new_route_name', '/some-path')
->controller('App\Controller\SomeController::index');

$routes->alias('some_route_name', 'new_route_name')
// this outputs the following generic deprecation message:
// 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.
// Since acme/package 1.2: The "some_route_name" route alias is deprecated. You should stop using it, as it will be removed in the future.
->deprecate('acme/package', '1.2', '')

// or

// 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.'
'The "%alias_id%" route alias is deprecated. Please use "new_route_name" instead.'
)
;

In this example, every time the ``new_route_name`` alias is used, a deprecation
warning is triggered, advising you to stop using that alias.
In this example, every time the ``some_route_name`` alias is used, a deprecation
warning is triggered, advising you to stop using this route and prefer using ``new_route_name``.

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