Skip to content
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

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

Open
wants to merge 2 commits 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
2 commits
Select commit Hold shift + click to select a range
9418739
fix(route-alias): Clarify route aliases examples with explicit route …
welcoMattic Feb 25, 2025
b3c04b6
Remove semicolon
welcoMattic Feb 25, 2025
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
44 changes: 31 additions & 13 deletions routing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1343,8 +1343,12 @@ Route alias allow you to have multiple name for the same route:
.. code-block:: yaml

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

alias_to_some_route_name:
alias: some_route_name # refers to the name of the route declared above

.. code-block:: xml

Expand All @@ -1355,7 +1359,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="alias_to_some_route_name" alias="some_route_name"/>
</routes>

.. code-block:: php
Expand All @@ -1364,10 +1370,13 @@ 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('alias_to_some_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 ``alias_to_some_route_name`` routes can
be used in the application and will produce the same result.

.. _routing-alias-deprecation:
Expand All @@ -1382,11 +1391,15 @@ you decided not to maintain it anymore), you can deprecate its definition:

.. code-block:: yaml

new_route_name:
alias: original_route_name
some_route_name:
path: /some-path
controller: App\Controller\SomeController::index

alias_to_some_route_name:
alias: some_route_name # refers to the name of the route declared above

# 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 "alias_to_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'
Expand All @@ -1405,9 +1418,11 @@ 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">
<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="alias_to_some_route_name" alias="some_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 "alias_to_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"/>

<!-- you can also define a custom deprecation message (%alias_id% placeholder is available) -->
Expand All @@ -1419,9 +1434,12 @@ you decided not to maintain it anymore), you can deprecate its definition:

.. code-block:: php

$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('alias_to_some_route_name', 'some_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 "alias_to_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', '')

// you can also define a custom deprecation message (%alias_id% placeholder is available)
Expand All @@ -1432,7 +1450,7 @@ you decided not to maintain it anymore), you can deprecate its definition:
)
;

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

The message is actually a message template, which replaces occurrences of the
Expand Down