diff --git a/routing.rst b/routing.rst
index 790ae314516..4d942793218 100644
--- a/routing.rst
+++ b/routing.rst
@@ -995,6 +995,136 @@ convert them automatically to their scalar values.
}
}
+Mapping Parameters
+~~~~~~~~~~~~~~~~~~
+
+By default, the route parameter (``{slug}`` for example) is the name of the argument
+injected to the controller method (``$slug``).
+
+You can change this behavior and define a mapping between route parameter and
+an argument name with ``{route_parameter_name:controller_argument_name}``:
+
+.. configuration-block::
+
+ .. code-block:: php-attributes
+
+ // src/Controller/BlogController.php
+ namespace App\Controller;
+
+ use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+ use Symfony\Component\HttpFoundation\Response;
+ use Symfony\Component\Routing\Attribute\Route;
+
+ class BlogController extends AbstractController
+ {
+ // ...
+
+ #[Route('/blog/{slug:articleSlug}', name: 'blog_show')]
+ public function show(string $articleSlug): Response
+ {
+ // $articleSlug will be equal to the dynamic part of the URL
+ // e.g. at /blog/yay-routing, then $articleSlug='yay-routing'
+
+ // ...
+ }
+ }
+
+ .. code-block:: yaml
+
+ # config/routes.yaml
+ blog_show:
+ path: /blog/{slug:articleSlug}
+ controller: App\Controller\BlogController::show
+
+ .. code-block:: xml
+
+
+
+
+
+
+
+
+ .. code-block:: php
+
+ // config/routes.php
+ use App\Controller\BlogController;
+ use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
+
+ return function (RoutingConfigurator $routes): void {
+ $routes->add('blog_show', '/blog/{slug:articleSlug}')
+ ->controller([BlogController::class, 'show'])
+ ;
+ };
+
+When two or more variable parts target the same argument name, argument will be
+an array:
+
+.. configuration-block::
+
+ .. code-block:: php-attributes
+
+ // src/Controller/BlogController.php
+ namespace App\Controller;
+
+ use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+ use Symfony\Component\HttpFoundation\Response;
+ use Symfony\Component\Routing\Attribute\Route;
+
+ class BlogController extends AbstractController
+ {
+ // ...
+
+ #[Route('/blog/{id:articleData}/{slug:articleData}', name: 'blog_show')]
+ public function show(array $articleData): Response
+ {
+ // $articleData will equal the dynamic part of the URL
+ // e.g. at /blog/12/yay-routing, then $articleData=['id' => '12', 'slug' => 'yay-routing']
+
+ // ...
+ }
+ }
+
+ .. code-block:: yaml
+
+ # config/routes.yaml
+ blog_show:
+ path: /blog/{id:articleData}/{slug:articleData}
+ controller: App\Controller\BlogController::show
+
+ .. code-block:: xml
+
+
+
+
+
+
+
+
+ .. code-block:: php
+
+ // config/routes.php
+ use App\Controller\BlogController;
+ use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
+
+ return function (RoutingConfigurator $routes): void {
+ $routes->add('blog_show', '/blog/{id:articleData}/{slug:articleData}')
+ ->controller([BlogController::class, 'show'])
+ ;
+ };
+
+.. versionadded:: 7.1
+
+ The mapping of route parameters was introduced in Symfony 7.1.
+
Special Parameters
~~~~~~~~~~~~~~~~~~