From 22cd58eb815c7c672ab3d4f7164ed8a51dcca7bd Mon Sep 17 00:00:00 2001
From: Mathieu Santostefano <msantostefano@proton.me>
Date: Sun, 9 Feb 2025 17:56:57 +0100
Subject: [PATCH] [Routing] Add Attribute code examples for alias in `#[Route]`
 attribute

---
 routing.rst | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)

diff --git a/routing.rst b/routing.rst
index e634a410c37..2f18b121472 100644
--- a/routing.rst
+++ b/routing.rst
@@ -1340,6 +1340,23 @@ have been renamed. Let's say you have a route called ``product_show``:
 
 .. configuration-block::
 
+    .. code-block:: php-attributes
+
+        // src/Controller/ProductController.php
+        namespace App\Controller;
+
+        use Symfony\Component\HttpFoundation\Response;
+        use Symfony\Component\Routing\Attribute\Route;
+
+        class ProductController
+        {
+            #[Route('/product/{id}', name: 'product_show')]
+            public function show(): Response
+            {
+                // ...
+            }
+        }
+
     .. code-block:: yaml
 
         # config/routes.yaml
@@ -1376,6 +1393,25 @@ Instead of duplicating the original route, you can create an alias for it.
 
 .. configuration-block::
 
+    .. code-block:: php-attributes
+
+        // src/Controller/ProductController.php
+        namespace App\Controller;
+
+        use Symfony\Component\HttpFoundation\Response;
+        use Symfony\Component\Routing\Attribute\Route;
+
+        class ProductController
+        {
+            // "alias" named argument indicates the name of the alias you want to create.
+            // The alias will point to the actual route "product_show"
+            #[Route('/product/{id}', name: 'product_show', alias: ['product_details'])]
+            public function show(): Response
+            {
+                // ...
+            }
+        }
+
     .. code-block:: yaml
 
         # config/routes.yaml
@@ -1416,6 +1452,15 @@ Instead of duplicating the original route, you can create an alias for it.
 In this example, both ``product_show`` and ``product_details`` routes can
 be used in the application and will produce the same result.
 
+.. note::
+
+    Using non-attributes formats (YAML, XML and PHP) is the only way
+    to define an alias pointing to a route that you don't own.
+
+    So that you can use your own route name for URL generation,
+    while actually using a route defined by a third-party bundle as the target of that URL generation,
+    as the 2 definitions are not required to be in the same config file (or even in the same format).
+
 .. _routing-alias-deprecation:
 
 Deprecating Route Aliases
@@ -1436,6 +1481,42 @@ This way, the ``product_show`` alias could be deprecated.
 
 .. configuration-block::
 
+    .. code-block:: php-attributes
+
+        // src/Controller/ProductController.php
+        namespace App\Controller;
+
+        use Symfony\Component\HttpFoundation\Response;
+        use Symfony\Component\Routing\Attribute\Route;
+
+        class ProductController
+        {
+            // this outputs the following generic deprecation message:
+            // Since acme/package 1.2: The "product_show" route alias is deprecated. You should stop using it, as it will be removed in the future.
+            #[Route('/product/{id}',
+                name: 'product_details',
+                alias: new DeprecatedAlias(
+                    aliasName: 'product_show',
+                    package: 'acme/package',
+                    version: '1.2',
+                ),
+            )]
+            // Or, you can also define a custom deprecation message (%alias_id% placeholder is available)
+            #[Route('/product/{id}',
+                name: 'product_details',
+                alias: new DeprecatedAlias(
+                    aliasName: 'product_show',
+                    package: 'acme/package',
+                    version: '1.2',
+                    message: 'The "%alias_id%" route alias is deprecated. Please use "product_details" instead.',
+                ),
+            )]
+            public function show(): Response
+            {
+                // ...
+            }
+        }
+
     .. code-block:: yaml
 
         # Move the concrete route definition under ``product_details``