Add #[ValueResolver] for specifying a controller argument resolver

Mathieu · Mathieu · commit e99a654a8ee1 · 2023-01-27T10:15:19.000+01:00
diff --git a/controller/value_resolver.rst b/controller/value_resolver.rst
@@ -355,3 +355,47 @@ command to see which argument resolvers are present and in which order they run:
 .. code-block:: terminal
 
     $ php bin/console debug:container debug.argument_resolver.inner --show-arguments
+
+Using a Specific Value Resolver
+-------------------------------
+
+.. versionadded:: 6.3
+
+    The ``ValueResolver`` attribute was introduced in Symfony 6.3.
+
+The priority-based system is designed to support the vast majority of use-cases,
+but it has limits: every resolver will be called until one provide some value.
+Not only is this inefficient if you already know how your parameter must be resolved,
+you could not even be sure which resolver did provide a value.
+
+You can tackle these two issues at once by adding a ``ValueResolver`` attribute
+to such parameters:
+
+    // src/Controller/DefaultController.php
+    namespace App\Controller;
+
+    use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\HttpKernel\Attribute\ValueResolver;
+    use Symfony\Component\HttpKernel\Controller\ArgumentResolver\DefaultValueResolver;
+    use Symfony\Component\Routing\Annotation\Route;
+
+    class DefaultController
+    {
+        #[Route('/{page}')]
+        public function list(
+            #[ValueResolver(DefaultValueResolver::class)]
+            int $page = 1,
+        ): Response {
+            /*
+             * Here $page would always be 1: the RequestAttributeValueResolver would not kick in
+             * because we asked the DefaultValueResolver only to provide a value.
+             */
+        }
+    }
+
+Its only argument is the resolver's name. That is,
+its definition's ``controller.argument_value_resolver`` tag ``name`` attribute.
+For built-in resolvers, this is the same as their FQCN.
+
+Note that the specified resolver **must** provide a value.
+Else, an exception will be thrown.
