@@ -861,6 +861,83 @@ control behavior:
861861
862862 The ``message `` option was introduced in Symfony 7.1.
863863
864+ Mapped Route Parameters
865+ ~~~~~~~~~~~~~~~~~~~~~~~
866+
867+ When many route parameters are used to find more than one entity, it is mandatory to use #[MapEntity] attributes and this can become cumbersome::
868+
869+ #[Route('/document/{slug}/{id}-{name}/')]
870+ public function showDocument(
871+ #[MapEntity(mapping: ['slug' => 'slug'])]
872+ Category $category,
873+ #[MapEntity(mapping: ['id' => 'id', 'name' => 'name'])]
874+ Document $document,
875+ ): Response
876+ {
877+ // the database queries in this case would be:
878+ // $document = $documentRepository->findOneBy(['id' => 'the id', 'name' => 'the name']);
879+ // $category = $categoryRepository->findOneBy(['slug' => 'the slug']);
880+ }
881+
882+ As an alternative, you can also use Mapped Route Parameters.
883+
884+ When adding route parameters, you can now define the mapping between the route parameter and the controller argument::
885+
886+ #[Route('/document/{slug:category}/{id:document}-{name:document}/')]
887+ public function showDocument(Document $document, Category $category): Response
888+ {
889+ // the database queries in this case would be:
890+ // $document = $documentRepository->findOneBy(['id' => 'the id', 'name' => 'the name']);
891+ // $category = $categoryRepository->findOneBy(['slug' => 'the slug']);
892+ }
893+
894+ ..versionadded ::7.1
895+
896+ The ``Mapped Route Parameters `` was introduced in Symfony 7.1.
897+
898+ But when two properties have the same name, you will catach an error if you try ::
899+
900+ #[Route('/document/{slug:category}/{id:document}-{slug:document}/')]
901+ public function showDocument(Document $document, Category $category): Response
902+ {
903+ // category entity and document entity have the same property ``slug`` but in the route_parameters we can't have two ``slug`` arguments.
904+ }
905+
906+ In this case we have to return to MapEntiy::
907+
908+ #[Route('/document/{slugCategory}/{id}-{slugDocument}/')]
909+ public function showDocument(
910+ #[MapEntity(mapping: ['slugCategory' => 'slug'])]
911+ Category $category
912+ #[MapEntity(mapping: ['id' => 'id', 'slugDocument' => 'slug'])]
913+ Document $document,
914+ ): Response
915+ {
916+ // the database queries in this case would be:
917+ // $document = $documentRepository->findOneBy(['id' => 'the id', 'slug' => 'the slug document']);
918+ // $category = $categoryRepository->findOneBy(['slug' => 'the slug category']);
919+ }
920+
921+ As an alternative, tou can use ``Aliased Mapped Route Parameters ``.
922+
923+ When adding route parameters, you can now define the mapping between the route parameter and the controller argument with an alias::
924+
925+ #[Route('/document/{slugCategory:category.slug}/{id:document}-{slugDocument:document.slug}/')]
926+ public function showDocument(Document $document, Category $category): Response
927+ {
928+ // the database queries in this case would be:
929+ // $document = $documentRepository->findOneBy(['id' => 'the id', 'slug' => 'the slug document']);
930+ // $category = $categoryRepository->findOneBy(['slug' => 'the slug category']);
931+ }
932+
933+ In this case, _route_mapping keys will be slugCategory and slugDocument, and used by path twig option::
934+
935+ {{ path('showDocument', {slugCategory: 'invoices', id: 25, slugDocument: 'invoice_CFD025125'}) }}
936+
937+ ..versionadded ::7.3
938+
939+ The ``Aliased Mapped Route Parameters `` was introduced in Symfony 7.3.
940+
864941Updating an Object
865942------------------
866943