fix(routing): Rename Route Alias route examples

Author: welcoMattic

routing.rst

@@ -1336,18 +1336,18 @@ A possible solution is to change the parameter requirements to be more permissiv
 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``
+Route alias allows you to have multiple names for the same route
+and can be used to provide backward compatibility for routes that
+have been renamed. Let's say you have a route called ``product_show``:
 
 .. configuration-block::
 
     .. code-block:: yaml
 
         # config/routes.yaml
-        some_route_name:
-            path: /some-path
-            controller: App\Controller\SomeController::index
+        product_show:
+            path: /product/{id}
+            controller: App\Controller\ProductController::show
 
     .. code-block:: xml
 
@@ -1358,7 +1358,7 @@ Let's say you have a route called ``some_route_name``
             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"/>
+            <route id="product_show" path="/product/{id}" controller="App\Controller\ProductController::show"/>
         </routes>
 
     .. code-block:: php
@@ -1367,27 +1367,27 @@ Let's say you have a route called ``some_route_name``
         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');
+            $routes->add('product_show', '/product/{id}')
+                    ->controller('App\Controller\ProductController::show');
         };
 
-Now, let's say you want to create a new route called ``new_route_name``
-that acts exactly the same as ``some_route_name``.
+Now, let's say you want to create a new route called ``product_details``
+that acts exactly the same as ``product_show``.
 
-Instead of duplicating the original route, you can create an alias for it. You can do this as follows:
+Instead of duplicating the original route, you can create an alias for it.
 
 .. configuration-block::
 
     .. code-block:: yaml
 
         # config/routes.yaml
-        some_route_name:
-            path: /some-path
-            controller: App\Controller\SomeController::index
+        product_show:
+            path: /product/{id}
+            controller: App\Controller\ProductController::show
 
-        new_route_name:
+        product_details:
             # "alias" option refers to the name of the route declared above
-            alias: some_route_name
+            alias: product_show
 
     .. code-block:: xml
 
@@ -1398,9 +1398,9 @@ Instead of duplicating the original route, you can create an alias for it. You c
             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"/>
+            <route id="product_show" path="/product/{id}" controller="App\Controller\ProductController::show"/>
             <!-- "alias" attribute value refers to the name of the route declared above -->
-            <route id="new_route_name" alias="some_route_name"/>
+            <route id="product_details" alias="product_show"/>
         </routes>
 
     .. code-block:: php
@@ -1409,13 +1409,13 @@ Instead of duplicating the original route, you can create an alias for it. You c
         use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 
         return static function (RoutingConfigurator $routes): void {
-            $routes->add('some_route_name', '/some_route_path')
-                    ->controller('App\Controller\SomeController::index');
+            $routes->add('product_show', '/product/{id}')
+                    ->controller('App\Controller\ProductController::show');
             // second argument refers to the name of the route declared above
-            $routes->alias('new_route_name', 'some_route_name');
+            $routes->alias('product_details', 'product_show');
         };
 
-In this example, both ``some_route_name`` and ``new_route_name`` routes can
+In this example, both ``product_show`` and ``product_details`` routes can
 be used in the application and will produce the same result.
 
 .. _routing-alias-deprecation:
@@ -1426,41 +1426,42 @@ Deprecating Route Aliases
 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.
+Now, let's say you want to replace the ``product_show`` route in favor of
+``product_details`` and mark the old one as deprecated.
 
-In the previous example, the alias ``new_route_name`` was pointing to
-``some_route_name`` route.
+In the previous example, the alias ``product_details`` was pointing to
+``product_show`` 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:
+To mark the ``product_show`` route as deprecated, you need to "switch" the alias.
+The ``product_show`` become the alias, and will now point to the ``product_details`` route.
+This way, the ``product_show`` alias could be deprecated.
 
 .. configuration-block::
 
     .. code-block:: yaml
 
-        # Move the concrete route definition under ``new_route_name``
-        new_route_name:
-            path: /some-path
-            controller: App\Controller\SomeController::index
+        # Move the concrete route definition under ``product_details``
+        product_details:
+            path: /product/{id}
+            controller: App\Controller\ProductController::show
 
-        # Define the alias and the deprecation under the ``some_route_name`` definition
-        some_route_name:
-            alias: new_route_name
+        # Define the alias and the deprecation under the ``product_show`` definition
+        product_show:
+            alias: product_details
 
             # this outputs the following generic deprecation message:
-            # 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.
+            # 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.
             deprecated:
                 package: 'acme/package'
                 version: '1.2'
 
             # or
 
-            # you can also define a custom deprecation message (%alias_id% placeholder is available)
+            # you can 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. Please use "new_route_name" instead.'
+                message: 'The "%alias_id%" route alias is deprecated. Please use "product_details" instead.'
 
     .. code-block:: xml
 
@@ -1470,46 +1471,46 @@ to be able to mark it as deprecated using the ``deprecated`` option:
             xsi:schemaLocation="http://symfony.com/schema/routing
                 https://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <!-- Move the concrete route definition under ``new_route_name`` -->
-            <route id="new_route_name" path="/some-path" controller="App\Controller\SomeController::index"/>
+            <!-- Move the concrete route definition under ``product_details`` -->
+            <route id="product_details" path="/product/{id}" controller="App\Controller\ProductController::show"/>
 
-            <!-- Define the alias and the deprecation under the ``some_route_name`` definition -->
-            <route id="some_route_name" alias="new_route_name">
+            <!-- Define the alias and the deprecation under the ``product_show`` definition -->
+            <route id="product_show" alias="product_details">
                 <!-- this outputs the following generic deprecation message:
-                     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. -->
+                     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. -->
                 <deprecated package="acme/package" version="1.2"/>
 
                 <!-- or -->
 
-                <!-- you can also define a custom deprecation message (%alias_id% placeholder is available) -->
+                <!-- you can define a custom deprecation message (%alias_id% placeholder is available) -->
                 <deprecated package="acme/package" version="1.2">
-                    The "%alias_id%" route alias is deprecated. Please use "new_route_name" instead.
+                    The "%alias_id%" route alias is deprecated. Please use "product_details" instead.
                 </deprecated>
             </route>
         </routes>
 
     .. code-block:: php
 
-        $routes->add('new_route_name', '/some-path')
-                ->controller('App\Controller\SomeController::index');
+        $routes->add('product_details', '/product/{id}')
+                ->controller('App\Controller\ProductController::show');
 
-        $routes->alias('some_route_name', 'new_route_name')
+        $routes->alias('product_show', 'product_details')
             // this outputs the following generic deprecation message:
-            // 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.
+            // 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.
             ->deprecate('acme/package', '1.2', '')
 
             // or
 
-            // you can also define a custom deprecation message (%alias_id% placeholder is available)
+            // you can define a custom deprecation message (%alias_id% placeholder is available)
             ->deprecate(
                 'acme/package',
                 '1.2',
-                'The "%alias_id%" route alias is deprecated. Please use "new_route_name" instead.'
+                'The "%alias_id%" route alias is deprecated. Please use "product_details" instead.'
             )
         ;
 
-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``.
+In this example, every time the ``product_show`` alias is used, a deprecation
+warning is triggered, advising you to stop using this route and prefer using ``product_details``.
 
 The message is actually a message template, which replaces occurrences of the
 ``%alias_id%`` placeholder by the route alias name. You **must** have