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 ~~~~~~~~~~~~~~~~~~~~~~