Add documentation about the Doctrine Entity Value Resolver

Author: jderusse

.doctor-rst.yaml

@@ -88,6 +88,7 @@ whitelist:
         - '.. versionadded:: 1.11' # Messenger (Middleware / DoctrineBundle)
         - '.. versionadded:: 1.18' # Flex in setup/upgrade_minor.rst
         - '.. versionadded:: 1.0.0' # Encore
+        - '.. versionadded:: 2.7.1' # Doctrine
         - '0 => 123' # assertion for var_dumper - components/var_dumper.rst
         - '1 => "foo"' # assertion for var_dumper - components/var_dumper.rst
         - '123,' # assertion for var_dumper - components/var_dumper.rst

best_practices.rst

@@ -246,16 +246,17 @@ Instead, you must use dependency injection to fetch services by
 :ref:`type-hinting action method arguments <controller-accessing-services>` or
 constructor arguments.
 
-Use ParamConverters If They Are Convenient
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Use EntityValueResolver If It Is Convenient
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If you're using :doc:`Doctrine </doctrine>`, then you can *optionally* use the
-`ParamConverter`_ to automatically query for an entity and pass it as an argument
-to your controller. It will also show a 404 page if no entity can be found.
+`EntityValueResolver`_ to automatically query for an entity and pass it as an
+argument to your controller. It will also show a 404 page if no entity can be
+found.
 
 If the logic to get an entity from a route variable is more complex, instead of
-configuring the ParamConverter, it's better to make the Doctrine query inside
-the controller (e.g. by calling to a :doc:`Doctrine repository method </doctrine>`).
+configuring the EntityValueResolver, it's better to make the Doctrine query
+inside the controller (e.g. by calling to a :doc:`Doctrine repository method </doctrine>`).
 
 Templates
 ---------

doctrine.rst

@@ -598,15 +598,59 @@ the :ref:`doctrine-queries` section.
     see the web debug toolbar, install the ``profiler`` :ref:`Symfony pack <symfony-packs>`
     by running this command: ``composer require --dev symfony/profiler-pack``.
 
-Automatically Fetching Objects (ParamConverter)
------------------------------------------------
+Automatically Fetching Objects (EntityValueResolver)
+----------------------------------------------------
 
-In many cases, you can use the `SensioFrameworkExtraBundle`_ to do the query
-for you automatically! First, install the bundle in case you don't have it:
+In many cases, you can use the `EntityValueResolver`_ to do the query for you
+automatically! First, enable the feature:
 
-.. code-block:: terminal
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/doctrine.yaml
+        doctrine:
+            orm:
+                controller_resolver:
+                    enabled: true
+                    auto_mapping: true
+                    evict_cache: false
+
+    .. code-block:: xml
+
+        <!-- config/packages/doctrine.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/doctrine
+                https://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
+
+            <doctrine:config>
+                <!-- by convention the env var names are always uppercase -->
+                <doctrine:orm>
+                    <doctrine:controller_resolver auto_mapping="true" evict_cache="false"/>
+                </doctrine:orm>
+            </doctrine:config>
+
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/doctrine.php
+        use Symfony\Config\DoctrineConfig;
 
-    $ composer require sensio/framework-extra-bundle
+        return static function (DoctrineConfig $doctrine) {
+            $controllerResolver = $doctrine->orm()
+                ->entityManager('default')
+                    // ...
+                    ->controllerResolver();
+
+            $controllerResolver->autoMapping(true);
+            $controllerResolver->evictCache(true);
+        };
 
 Now, simplify your controller::
 
@@ -632,7 +676,54 @@ Now, simplify your controller::
 That's it! The bundle uses the ``{id}`` from the route to query for the ``Product``
 by the ``id`` column. If it's not found, a 404 page is generated.
 
-There are many more options you can use. Read more about the `ParamConverter`_.
+This behavior can be enabled on all your controllers, by setting the ``auto_mapping``
+parameter to ``true``. Or individually on the desired controllers by using the
+``MapEntity`` attribute:
+
+    // src/Controller/ProductController.php
+    namespace App\Controller;
+
+    use App\Entity\Product;
+    use App\Repository\ProductRepository;
+    use Symfony\Bridge\Doctrine\Attribute\MapEntity;
+    use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\Routing\Annotation\Route;
+    // ...
+
+    class ProductController extends AbstractController
+    {
+        #[Route('/product/{id}', name: 'product_show')]
+        public function show(
+            #[MapEntity]
+            Product $product
+        ): Response {
+            // use the Product!
+            // ...
+        }
+    }
+
+.. tip::
+
+    When enabled globally, it's possible to disabled the behavior on a specific
+    controller, by using the ``MapEntity`` set to ``disabled``.
+
+        public function show(
+            #[CurrentUser]
+            #[MapEntity(disabled: true)]
+            User $user
+        ): Response {
+            // User is not resolved by the EntityValueResolver
+            // ...
+        }
+
+.. versionadded:: 6.2
+
+    Entity Value Resolver was introduced in Symfony 6.2.
+
+.. versionadded:: 2.7.1
+
+    Autowiring of the EntityValueResolver was introduced in DoctrineBundle
+    2.7.1.
 
 Updating an Object
 ------------------
@@ -896,7 +987,6 @@ Learn more
 .. _`DoctrineMigrationsBundle`: https://github.com/doctrine/DoctrineMigrationsBundle
 .. _`NativeQuery`: https://www.doctrine-project.org/projects/doctrine-orm/en/current/reference/native-sql.html
 .. _`SensioFrameworkExtraBundle`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/index.html
-.. _`ParamConverter`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
 .. _`limit of 767 bytes for the index key prefix`: https://dev.mysql.com/doc/refman/5.6/en/innodb-limits.html
 .. _`Doctrine screencast series`: https://symfonycasts.com/screencast/symfony-doctrine
 .. _`API Platform`: https://api-platform.com/docs/core/validation/