From e37a9dc3dc191f3f82ffaea3f11da84b2056071b Mon Sep 17 00:00:00 2001 From: eltharin Date: Mon, 24 Mar 2025 11:31:16 +0100 Subject: [PATCH 1/8] add mapped route parameters and aliases --- doctrine.rst | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/doctrine.rst b/doctrine.rst index 171f8a3348a..14d79d378f9 100644 --- a/doctrine.rst +++ b/doctrine.rst @@ -861,6 +861,83 @@ 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 + { + // the database queries in this case would be: + // $document = $documentRepository->findOneBy(['id' => 'the id', 'name' => 'the name']); + // $category = $categoryRepository->findOneBy(['slug' => 'the slug']); + } + +As an alternative, you can also use Mapped Route Parameters. + +When adding route parameters, you can now 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 + { + // the database queries in this case would be: + // $document = $documentRepository->findOneBy(['id' => 'the id', 'name' => 'the name']); + // $category = $categoryRepository->findOneBy(['slug' => 'the slug']); + } + +.. versionadded:: 7.1 + + The ``Mapped Route Parameters`` was introduced in Symfony 7.1. + +But when two properties have the same name, you will catach an error if you try :: + + #[Route('/document/{slug:category}/{id:document}-{slug:document}/')] + public function showDocument(Document $document, Category $category): Response + { + // category entity and document entity have the same property ``slug`` but in the route_parameters we can't have two ``slug`` arguments. + } + +In this case we have to return to MapEntiy:: + + #[Route('/document/{slugCategory}/{id}-{slugDocument}/')] + public function showDocument( + #[MapEntity(mapping: ['slugCategory' => 'slug'])] + Category $category + #[MapEntity(mapping: ['id' => 'id', 'slugDocument' => 'slug'])] + Document $document, + ): Response + { + // the database queries in this case would be: + // $document = $documentRepository->findOneBy(['id' => 'the id', 'slug' => 'the slug document']); + // $category = $categoryRepository->findOneBy(['slug' => 'the slug category']); + } + +As an alternative, tou can use ``Aliased Mapped Route Parameters``. + +When adding route parameters, you can now define the mapping between the route parameter and the controller argument with an alias:: + + #[Route('/document/{slugCategory:category.slug}/{id:document}-{slugDocument:document.slug}/')] + public function showDocument(Document $document, Category $category): Response + { + // the database queries in this case would be: + // $document = $documentRepository->findOneBy(['id' => 'the id', 'slug' => 'the slug document']); + // $category = $categoryRepository->findOneBy(['slug' => 'the slug category']); + } + +In this case, _route_mapping keys will be slugCategory and slugDocument, and used by path twig option:: + + {{ path('showDocument', {slugCategory: 'invoices', id: 25, slugDocument: 'invoice_CFD025125'}) }} + +.. versionadded:: 7.3 + + The ``Aliased Mapped Route Parameters`` was introduced in Symfony 7.3. + Updating an Object ------------------ From 36cdca56449aaa2b8312b1962fb0c42a4321abdb Mon Sep 17 00:00:00 2001 From: eltharin Date: Mon, 24 Mar 2025 19:11:56 +0100 Subject: [PATCH 2/8] corrections --- doctrine.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doctrine.rst b/doctrine.rst index 14d79d378f9..7b7cc4758c9 100644 --- a/doctrine.rst +++ b/doctrine.rst @@ -864,7 +864,8 @@ control behavior: 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:: +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( @@ -918,7 +919,7 @@ In this case we have to return to MapEntiy:: // $category = $categoryRepository->findOneBy(['slug' => 'the slug category']); } -As an alternative, tou can use ``Aliased Mapped Route Parameters``. +As an alternative, you can use ``Aliased Mapped Route Parameters``. When adding route parameters, you can now define the mapping between the route parameter and the controller argument with an alias:: From a60587cd95705a4a9a19f130836a6eb69466e182 Mon Sep 17 00:00:00 2001 From: eltharin Date: Mon, 24 Mar 2025 22:00:44 +0100 Subject: [PATCH 3/8] Update doctrine.rst Co-authored-by: Matthieu Lempereur --- doctrine.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doctrine.rst b/doctrine.rst index 7b7cc4758c9..713e39b54eb 100644 --- a/doctrine.rst +++ b/doctrine.rst @@ -865,7 +865,7 @@ 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:: +it is mandatory to use ``#[MapEntity]`` attributes and this can become cumbersome:: #[Route('/document/{slug}/{id}-{name}/')] public function showDocument( From ab4ac88c4b425fb81ae66c7a954415d5d1988356 Mon Sep 17 00:00:00 2001 From: eltharin Date: Tue, 25 Mar 2025 06:54:09 +0100 Subject: [PATCH 4/8] remove traillingslash and backticks --- doctrine.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doctrine.rst b/doctrine.rst index 713e39b54eb..5232534315f 100644 --- a/doctrine.rst +++ b/doctrine.rst @@ -867,7 +867,7 @@ 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}/')] + #[Route('/document/{slug}/{id}-{name}')] public function showDocument( #[MapEntity(mapping: ['slug' => 'slug'])] Category $category, @@ -884,7 +884,7 @@ As an alternative, you can also use Mapped Route Parameters. When adding route parameters, you can now define the mapping between the route parameter and the controller argument:: - #[Route('/document/{slug:category}/{id:document}-{name:document}/')] + #[Route('/document/{slug:category}/{id:document}-{name:document}')] public function showDocument(Document $document, Category $category): Response { // the database queries in this case would be: @@ -894,11 +894,11 @@ When adding route parameters, you can now define the mapping between the route p .. versionadded:: 7.1 - The ``Mapped Route Parameters`` was introduced in Symfony 7.1. + The Mapped Route Parameters was introduced in Symfony 7.1. But when two properties have the same name, you will catach an error if you try :: - #[Route('/document/{slug:category}/{id:document}-{slug:document}/')] + #[Route('/document/{slug:category}/{id:document}-{slug:document}')] public function showDocument(Document $document, Category $category): Response { // category entity and document entity have the same property ``slug`` but in the route_parameters we can't have two ``slug`` arguments. @@ -906,7 +906,7 @@ But when two properties have the same name, you will catach an error if you try In this case we have to return to MapEntiy:: - #[Route('/document/{slugCategory}/{id}-{slugDocument}/')] + #[Route('/document/{slugCategory}/{id}-{slugDocument}')] public function showDocument( #[MapEntity(mapping: ['slugCategory' => 'slug'])] Category $category @@ -919,11 +919,11 @@ In this case we have to return to MapEntiy:: // $category = $categoryRepository->findOneBy(['slug' => 'the slug category']); } -As an alternative, you can use ``Aliased Mapped Route Parameters``. +As an alternative, you can use Aliased Mapped Route Parameters. When adding route parameters, you can now define the mapping between the route parameter and the controller argument with an alias:: - #[Route('/document/{slugCategory:category.slug}/{id:document}-{slugDocument:document.slug}/')] + #[Route('/document/{slugCategory:category.slug}/{id:document}-{slugDocument:document.slug}')] public function showDocument(Document $document, Category $category): Response { // the database queries in this case would be: @@ -937,7 +937,7 @@ In this case, _route_mapping keys will be slugCategory and slugDocument, and use .. versionadded:: 7.3 - The ``Aliased Mapped Route Parameters`` was introduced in Symfony 7.3. + The Aliased Mapped Route Parameters was introduced in Symfony 7.3. Updating an Object ------------------ From c0ead98d1883fcdcb84d428f3cb8597141caee80 Mon Sep 17 00:00:00 2001 From: eltharin Date: Tue, 25 Mar 2025 06:58:08 +0100 Subject: [PATCH 5/8] MrYamous changes --- doctrine.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doctrine.rst b/doctrine.rst index 5232534315f..08e3a26f2aa 100644 --- a/doctrine.rst +++ b/doctrine.rst @@ -909,7 +909,7 @@ In this case we have to return to MapEntiy:: #[Route('/document/{slugCategory}/{id}-{slugDocument}')] public function showDocument( #[MapEntity(mapping: ['slugCategory' => 'slug'])] - Category $category + Category $category, #[MapEntity(mapping: ['id' => 'id', 'slugDocument' => 'slug'])] Document $document, ): Response @@ -931,7 +931,9 @@ When adding route parameters, you can now define the mapping between the route p // $category = $categoryRepository->findOneBy(['slug' => 'the slug category']); } -In this case, _route_mapping keys will be slugCategory and slugDocument, and used by path twig option:: +In this case, _route_mapping keys will be slugCategory and slugDocument, and used by path twig option. + +.. code-block:: twig {{ path('showDocument', {slugCategory: 'invoices', id: 25, slugDocument: 'invoice_CFD025125'}) }} From 23a1f0da0662856347f7def685954737002387fc Mon Sep 17 00:00:00 2001 From: eltharin Date: Tue, 25 Mar 2025 07:56:37 +0100 Subject: [PATCH 6/8] was-were --- doctrine.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doctrine.rst b/doctrine.rst index 08e3a26f2aa..0f24ab36b7b 100644 --- a/doctrine.rst +++ b/doctrine.rst @@ -894,7 +894,7 @@ When adding route parameters, you can now define the mapping between the route p .. versionadded:: 7.1 - The Mapped Route Parameters was introduced in Symfony 7.1. + The mapped route parameters were introduced in Symfony 7.1. But when two properties have the same name, you will catach an error if you try :: @@ -939,7 +939,7 @@ In this case, _route_mapping keys will be slugCategory and slugDocument, and use .. versionadded:: 7.3 - The Aliased Mapped Route Parameters was introduced in Symfony 7.3. + The aliased mapped route parameters were introduced in Symfony 7.3. Updating an Object ------------------ From 286ba1b6b95a0b20c6013b504acd08a17bbc14bb Mon Sep 17 00:00:00 2001 From: eltharin Date: Tue, 25 Mar 2025 11:00:54 +0100 Subject: [PATCH 7/8] update from comments --- doctrine.rst | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/doctrine.rst b/doctrine.rst index 0f24ab36b7b..1e1309c4027 100644 --- a/doctrine.rst +++ b/doctrine.rst @@ -875,26 +875,24 @@ it is mandatory to use ``#[MapEntity]`` attributes and this can become cumbersom Document $document, ): Response { - // the database queries in this case would be: + // this would result in the following database queries: // $document = $documentRepository->findOneBy(['id' => 'the id', 'name' => 'the name']); // $category = $categoryRepository->findOneBy(['slug' => 'the slug']); } -As an alternative, you can also use Mapped Route Parameters. - -When adding route parameters, you can now define the mapping between the route parameter and the controller argument:: +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 { - // the database queries in this case would be: + // 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 - The mapped route parameters were introduced in Symfony 7.1. + Mapped route parameters were introduced in Symfony 7.1. But when two properties have the same name, you will catach an error if you try :: @@ -914,7 +912,7 @@ In this case we have to return to MapEntiy:: Document $document, ): Response { - // the database queries in this case would be: + // this would result in the following database queries: // $document = $documentRepository->findOneBy(['id' => 'the id', 'slug' => 'the slug document']); // $category = $categoryRepository->findOneBy(['slug' => 'the slug category']); } @@ -926,7 +924,7 @@ When adding route parameters, you can now define the mapping between the route p #[Route('/document/{slugCategory:category.slug}/{id:document}-{slugDocument:document.slug}')] public function showDocument(Document $document, Category $category): Response { - // the database queries in this case would be: + // this would result in the following database queries: // $document = $documentRepository->findOneBy(['id' => 'the id', 'slug' => 'the slug document']); // $category = $categoryRepository->findOneBy(['slug' => 'the slug category']); } From 63db3a4a73912807a3844f5a5af4dc8b08186dca Mon Sep 17 00:00:00 2001 From: eltharin Date: Tue, 25 Mar 2025 11:01:41 +0100 Subject: [PATCH 8/8] remove the --- doctrine.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doctrine.rst b/doctrine.rst index 1e1309c4027..71638e67e85 100644 --- a/doctrine.rst +++ b/doctrine.rst @@ -937,7 +937,7 @@ In this case, _route_mapping keys will be slugCategory and slugDocument, and use .. versionadded:: 7.3 - The aliased mapped route parameters were introduced in Symfony 7.3. + Aliased mapped route parameters were introduced in Symfony 7.3. Updating an Object ------------------