From e591c5903958e63eaf1bc7d9b470431b29904f8c Mon Sep 17 00:00:00 2001 From: Nicolas Grekas Date: Mon, 12 May 2025 15:16:58 +0200 Subject: [PATCH] [Routing] Tell about {foo:bar} mapping syntax --- doctrine.rst | 31 +++++++++++-------------------- routing.rst | 43 ++++++++++++++++++++++++++++++++----------- 2 files changed, 43 insertions(+), 31 deletions(-) diff --git a/doctrine.rst b/doctrine.rst index 171f8a3348a..270c59a08c4 100644 --- a/doctrine.rst +++ b/doctrine.rst @@ -680,7 +680,7 @@ will automatically fetch them:: /** * Perform a findOneBy() where the slug property matches {slug}. */ - #[Route('/product/{slug}')] + #[Route('/product/{slug:product}')] public function showBySlug(Product $product): Response { } @@ -694,14 +694,17 @@ Automatic fetching works in these situations: *all* of the wildcards in your route that are actually properties on your entity (non-properties are ignored). -This behavior is enabled by default on all controllers. If you prefer, you can -restrict this feature to only work on route wildcards called ``id`` to look for -entities by primary key. To do so, set the option -``doctrine.orm.controller_resolver.auto_mapping`` to ``false``. +The ``{slug:product}`` syntax maps the route parameter named ``slug`` to the +controller argument named ``$product``. It also hints the resolver to lookup +by slug when loading the corresponding ``Product`` object from the database. -When ``auto_mapping`` is disabled, you can configure the mapping explicitly for -any controller argument with the ``MapEntity`` attribute. You can even control -the ``EntityValueResolver`` behavior by using the `MapEntity options`_ :: +.. versionadded:: 7.1 + + Route parameter mapping was introduced in Symfony 7.1. + +You can also configure the mapping explicitly for any controller argument +with the ``MapEntity`` attribute. You can even control the +``EntityValueResolver`` behavior by using the `MapEntity options`_ :: // src/Controller/ProductController.php namespace App\Controller; @@ -812,18 +815,6 @@ control behavior: ): Response { } -``exclude`` - Configures the properties that should be used in the ``findOneBy()`` - method by *excluding* one or more properties so that not *all* are used:: - - #[Route('/product/{slug}/{date}')] - public function show( - #[MapEntity(exclude: ['date'])] - Product $product, - \DateTime $date - ): Response { - } - ``stripNull`` If true, then when ``findOneBy()`` is used, any values that are ``null`` will not be used for the query. diff --git a/routing.rst b/routing.rst index 24218eaf74c..587a35f269b 100644 --- a/routing.rst +++ b/routing.rst @@ -22,8 +22,7 @@ Creating Routes as Attributes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ PHP attributes allow to define routes next to the code of the -:doc:`controllers ` associated to those routes. Attributes are -native in PHP 8 and higher versions, so you can use them right away. +:doc:`controllers ` associated to those routes. You need to add a bit of configuration to your project before using them. If your project uses :ref:`Symfony Flex `, this file is already created for you. @@ -707,12 +706,6 @@ URL Route Parameters matches any uppercase character in any language, ``\p{Greek}`` matches any Greek characters, etc. -.. note:: - - When using regular expressions in route parameters, you can set the ``utf8`` - route option to ``true`` to make any ``.`` character match any UTF-8 - characters instead of just a single byte. - If you prefer, requirements can be inlined in each parameter using the syntax ``{parameter_name}``. This feature makes configuration more concise, but it can decrease route readability when requirements are complex: @@ -998,7 +991,7 @@ controller action. Instead of ``string $slug``, add ``BlogPost $post``:: { // ... - #[Route('/blog/{slug}', name: 'blog_show')] + #[Route('/blog/{slug:post}', name: 'blog_show')] public function show(BlogPost $post): Response { // $post is the object whose slug matches the routing parameter @@ -1012,9 +1005,37 @@ this case), the "param converter" makes a database request to find the object using the request parameters (``slug`` in this case). If no object is found, Symfony generates a 404 response automatically. +The ``{slug:post}`` syntax maps the route parameter named ``slug`` to the controller +argument named ``$post``. It also hints the "param converter" to lookup by slug +when loading the corresponding ``BlogPost`` object from the database. + +.. versionadded:: 7.1 + + Route parameter mapping was introduced in Symfony 7.1. + +When more than one entity needs to be derived from route parameters, collisions can happen. +In the following example, the route tries to define two mappings: one to load an author by +name, two to load a category by name. But this is not allowed because from the side of the +route definition, this declares a parameter named "name" twice:: + + #[Route('/search-book/{name:author}/{name:category}')] + +Such routes should instead be defined using the following syntax:: + + #[Route('/search-book/{authorName:author.name}/{categoryName:category.name}')] + +This way, the route parameter names are unique (``authorName`` and ``categoryName``) and +the "param converter" can correctly map them to controller arguments (``$author`` and +``$category``), loading them both by their name. + +.. versionadded:: 7.3 + + This more advanced style of route parameter mapping was introduced in Symfony 7.3. + +More advanced mappings can be achieved using the ``#[MapEntity]`` attribute. Check out the :ref:`Doctrine param conversion documentation ` -to learn about the ``#[MapEntity]`` attribute that can be used to customize the -database queries used to fetch the object from the route parameter. +to learn how to customize the database queries used to fetch the object from the route +parameter. Backed Enum Parameters ~~~~~~~~~~~~~~~~~~~~~~ pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.

Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy