From d65f27b39571d73b36372a34c2c95243ceaf5368 Mon Sep 17 00:00:00 2001
From: Mathieu Santostefano <msantostefano@proton.me>
Date: Sun, 9 Feb 2025 17:56:57 +0100
Subject: [PATCH] docs(routing): Add Attribute code examples for alias in
#[Route] attribute
---
routing.rst | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 64 insertions(+)
diff --git a/routing.rst b/routing.rst
index 4ab0dce2a82..43689e1940f 100644
--- a/routing.rst
+++ b/routing.rst
@@ -1307,8 +1307,34 @@ Route Aliasing
Route alias allow you to have multiple name for the same route:
+.. note::
+
+ In next code examples in YAML, XML and PHP, ``original_route_name`` is an existing route,
+ ``new_route_name`` is a new route whose alias refers to ``original_route_name``.
+
+ In Attribute code example, ``original_route_name`` is NOT an existing route.
+ ``new_route_name`` is the new name of a route which was previously named ``original_route_name``.
+
.. configuration-block::
+ .. code-block:: php-attributes
+
+ // src/Controller/DefaultController.php
+ namespace App\Controller;
+
+ use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+ use Symfony\Component\HttpFoundation\Response;
+ use Symfony\Component\Routing\Attribute\Route;
+
+ class DefaultController extends AbstractController
+ {
+ #[Route('/path', name: 'new_route_name', alias: ['original_route_name'])]
+ public function action(): Response
+ {
+ // ...
+ }
+ }
+
.. code-block:: yaml
# config/routes.yaml
@@ -1349,6 +1375,44 @@ you decided not to maintain it anymore), you can deprecate its definition:
.. configuration-block::
+ .. code-block:: php-attributes
+
+ // src/Controller/DefaultController.php
+ namespace App\Controller;
+
+ use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+ use Symfony\Component\HttpFoundation\Response;
+ use Symfony\Component\Routing\Attribute\Route;
+
+ class DefaultController extends AbstractController
+ {
+ // 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.
+ #[Route('/path',
+ name: 'new_route_name',
+ alias: new DeprecatedAlias(aliasName: 'original_route_name', package: 'acme/package', version: '1.2')
+ )]
+ // you can also define a custom deprecation message (%alias_id% placeholder is available)
+ #[Route('/path',
+ name: 'new_route_name',
+ alias: new DeprecatedAlias(aliasName: 'original_route_name', package: 'acme/package', version: '1.2', message: 'The "%alias_id%" route alias is deprecated. Do not use it anymore.')
+ )]
+ public function action(): Response
+ {
+ // ...
+ }
+
+ #[Route('/path', name: 'new_route_name', alias: [
+ new DeprecatedAlias('first_original_route_name', 'acme/package', '1.0'),
+ new DeprecatedAlias('second_original_route_name', 'acme/package', '2.0'),
+ new DeprecatedAlias('third_original_route_name', 'acme/package', '3.0'),
+ ])]
+ public function another_action()
+ {
+ // ...
+ }
+ }
+
.. code-block:: yaml
new_route_name: