[Routing] document mapped route parameters

doctrine.rst

@@ -861,6 +861,39 @@ control behavior:
 
     The ``message`` option was introduced in Symfony 7.1.
 
+Mapped Route Parameters
+~~~~~~~~~~~~~~~~~~~~~~~
+
+When many route parameters are used to find more than one entity,
+it is mandatory to use ``#[MapEntity]`` attributes and this can become cumbersome::
+
+    #[Route('/document/{slug}/{id}-{name}')]
+    public function showDocument(
+        #[MapEntity(mapping: ['slug' => 'slug'])]
+        Category $category,
+        #[MapEntity(mapping: ['id' => 'id', 'name' => 'name'])]
+        Document $document,
+    ): Response
+    {
+        // this would result in the following database queries:
+        // $document = $documentRepository->findOneBy(['id' => 'the id', 'name' => 'the name']);
+        // $category = $categoryRepository->findOneBy(['slug' => 'the slug']);
+    }
+
+By using mapped route parameters, you can define the mapping between the route parameter and the controller argument::
+
+    #[Route('/document/{slug:category}/{id:document}-{name:document}')]
+    public function showDocument(Document $document, Category $category): Response
+    {
+        // this would result in the following database queries:
+        // $document = $documentRepository->findOneBy(['id' => 'the id', 'name' => 'the name']);
+        // $category = $categoryRepository->findOneBy(['slug' => 'the slug']);
+    }
+
+.. versionadded:: 7.1
+
+    Mapped route parameters were introduced in Symfony 7.1.
+
 Updating an Object
 ------------------