feature #48992 [HttpKernel] Introduce pinnable value resolvers with #[ValueResolver] and #[AsPinnedValueResolver] (MatTheCat)

nicolas-grekas · nicolas-grekas · commit c9aeb2561fd1 · 2023-03-06T14:48:37.000+01:00
This PR was merged into the 6.3 branch. Discussion ---------- [HttpKernel] Introduce pinnable value resolvers with `#[ValueResolver]` and `#[AsPinnedValueResolver]` | Q | A | ------------- | --- | Branch? | 6.3 | Bug fix? | no | New feature? | yes | Deprecations? | no | Tickets | Fix #48927 | License | MIT | Doc PR | symfony/symfony-docs#17763 Introducing a new `ValueResolver` attribute, which allows to - “pin” a value resolver to an argument, meaning only said resolver will be called - prevent a resolver to be called for an argument Every existing resolver-related attribute (`MapEntity`, `CurrentUser`…) now extends `ValueResolver`. Each `controller.argument_value_resolver` tag is added a `name` attribute, which is the resolver’s FQCN. This is the first argument `ValueResolver` expects. A new `AsPinnedValueResolver` attribute is added for autoconfiguration, adding the `controller.pinned_value_resolver` tag. Such resolvers can only be “pinned”, meaning they won’t ever be called for an argument missing the `ValueResolver` attribute. Commits ------- 245485c2a7 [HttpKernel] Introduce pinnable value resolvers with `#[ValueResolver]` and `#[AsPinnedValueResolver]`
diff --git a/Attribute/AsPinnedValueResolver.php b/Attribute/AsPinnedValueResolver.php
@@ -0,0 +1,24 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\HttpKernel\Attribute;
+
+/**
+ * Service tag to autoconfigure pinned value resolvers.
+ */
+#[\Attribute(\Attribute::TARGET_CLASS)]
+class AsPinnedValueResolver
+{
+    public function __construct(
+        public readonly ?string $name = null,
+    ) {
+    }
+}
diff --git a/Attribute/MapDateTime.php b/Attribute/MapDateTime.php
@@ -11,14 +11,19 @@
 
 namespace Symfony\Component\HttpKernel\Attribute;
 
+use Symfony\Component\HttpKernel\Controller\ArgumentResolver\DateTimeValueResolver;
+
 /**
  * Controller parameter tag to configure DateTime arguments.
  */
 #[\Attribute(\Attribute::TARGET_PARAMETER)]
-class MapDateTime
+class MapDateTime extends ValueResolver
 {
     public function __construct(
-        public readonly ?string $format = null
+        public readonly ?string $format = null,
+        bool $disabled = false,
+        string $resolver = DateTimeValueResolver::class,
     ) {
+        parent::__construct($resolver, $disabled);
     }
 }
diff --git a/Attribute/ValueResolver.php b/Attribute/ValueResolver.php
@@ -0,0 +1,27 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\HttpKernel\Attribute;
+
+use Symfony\Component\HttpKernel\Controller\ValueResolverInterface;
+
+#[\Attribute(\Attribute::TARGET_PARAMETER | \Attribute::IS_REPEATABLE)]
+class ValueResolver
+{
+    /**
+     * @param class-string<ValueResolverInterface>|string $name
+     */
+    public function __construct(
+        public string $name,
+        public bool $disabled = false,
+    ) {
+    }
+}
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,6 +10,7 @@ CHANGELOG
  * Use an instance of `Psr\Clock\ClockInterface` to generate the current date time in `DateTimeValueResolver`
  * Add `#[WithLogLevel]` for defining log levels for exceptions
  * Add `skip_response_headers` to the `HttpCache` options
+ * Introduce pinnable value resolvers with `#[ValueResolver]` and `#[AsPinnedValueResolver]`
 
 6.2
 ---
diff --git a/Controller/ArgumentResolver.php b/Controller/ArgumentResolver.php
@@ -11,7 +11,9 @@
 
 namespace Symfony\Component\HttpKernel\Controller;
 
+use Psr\Container\ContainerInterface;
 use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpKernel\Attribute\ValueResolver;
 use Symfony\Component\HttpKernel\Controller\ArgumentResolver\DefaultValueResolver;
 use Symfony\Component\HttpKernel\Controller\ArgumentResolver\RequestAttributeValueResolver;
 use Symfony\Component\HttpKernel\Controller\ArgumentResolver\RequestValueResolver;
@@ -20,6 +22,8 @@
 use Symfony\Component\HttpKernel\Controller\ArgumentResolver\VariadicValueResolver;
 use Symfony\Component\HttpKernel\ControllerMetadata\ArgumentMetadataFactory;
 use Symfony\Component\HttpKernel\ControllerMetadata\ArgumentMetadataFactoryInterface;
+use Symfony\Component\HttpKernel\Exception\ResolverNotFoundException;
+use Symfony\Contracts\Service\ServiceProviderInterface;
 
 /**
  * Responsible for resolving the arguments passed to an action.
@@ -30,25 +34,54 @@ final class ArgumentResolver implements ArgumentResolverInterface
 {
     private ArgumentMetadataFactoryInterface $argumentMetadataFactory;
     private iterable $argumentValueResolvers;
+    private ?ContainerInterface $namedResolvers;
 
     /**
      * @param iterable<mixed, ArgumentValueResolverInterface|ValueResolverInterface> $argumentValueResolvers
      */
-    public function __construct(ArgumentMetadataFactoryInterface $argumentMetadataFactory = null, iterable $argumentValueResolvers = [])
+    public function __construct(ArgumentMetadataFactoryInterface $argumentMetadataFactory = null, iterable $argumentValueResolvers = [], ContainerInterface $namedResolvers = null)
     {
         $this->argumentMetadataFactory = $argumentMetadataFactory ?? new ArgumentMetadataFactory();
         $this->argumentValueResolvers = $argumentValueResolvers ?: self::getDefaultArgumentValueResolvers();
+        $this->namedResolvers = $namedResolvers;
     }
 
     public function getArguments(Request $request, callable $controller, \ReflectionFunctionAbstract $reflector = null): array
     {
         $arguments = [];
 
         foreach ($this->argumentMetadataFactory->createArgumentMetadata($controller, $reflector) as $metadata) {
-            foreach ($this->argumentValueResolvers as $resolver) {
+            $argumentValueResolvers = $this->argumentValueResolvers;
+            $disabledResolvers = [];
+
+            if ($this->namedResolvers && $attributes = $metadata->getAttributesOfType(ValueResolver::class, $metadata::IS_INSTANCEOF)) {
+                $resolverName = null;
+                foreach ($attributes as $attribute) {
+                    if ($attribute->disabled) {
+                        $disabledResolvers[$attribute->name] = true;
+                    } elseif ($resolverName) {
+                        throw new \LogicException(sprintf('You can only pin one resolver per argument, but argument "$%s" of "%s()" has more.', $metadata->getName(), $this->getPrettyName($controller)));
+                    } else {
+                        $resolverName = $attribute->name;
+                    }
+                }
+
+                if ($resolverName) {
+                    if (!$this->namedResolvers->has($resolverName)) {
+                        throw new ResolverNotFoundException($resolverName, $this->namedResolvers instanceof ServiceProviderInterface ? array_keys($this->namedResolvers->getProvidedServices()) : []);
+                    }
+
+                    $argumentValueResolvers = [$this->namedResolvers->get($resolverName)];
+                }
+            }
+
+            foreach ($argumentValueResolvers as $name => $resolver) {
                 if ((!$resolver instanceof ValueResolverInterface || $resolver instanceof TraceableValueResolver) && !$resolver->supports($request, $metadata)) {
                     continue;
                 }
+                if (isset($disabledResolvers[\is_int($name) ? $resolver::class : $name])) {
+                    continue;
+                }
 
                 $count = 0;
                 foreach ($resolver->resolve($request, $metadata) as $argument) {
@@ -70,15 +103,7 @@ public function getArguments(Request $request, callable $controller, \Reflection
                 }
             }
 
-            $representative = $controller;
-
-            if (\is_array($representative)) {
-                $representative = sprintf('%s::%s()', $representative[0]::class, $representative[1]);
-            } elseif (\is_object($representative)) {
-                $representative = get_debug_type($representative);
-            }
-
-            throw new \RuntimeException(sprintf('Controller "%s" requires that you provide a value for the "$%s" argument. Either the argument is nullable and no null value has been provided, no default value has been provided or because there is a non optional argument after this one.', $representative, $metadata->getName()));
+            throw new \RuntimeException(sprintf('Controller "%s" requires that you provide a value for the "$%s" argument. Either the argument is nullable and no null value has been provided, no default value has been provided or because there is a non optional argument after this one.', $this->getPrettyName($controller), $metadata->getName()));
         }
 
         return $arguments;
@@ -97,4 +122,17 @@ public static function getDefaultArgumentValueResolvers(): iterable
             new VariadicValueResolver(),
         ];
     }
+
+    private function getPrettyName($controller): string
+    {
+        if (\is_array($controller)) {
+            return $controller[0]::class.'::'.$controller[1];
+        }
+
+        if (\is_object($controller)) {
+            return get_debug_type($controller);
+        }
+
+        return $controller;
+    }
 }
diff --git a/DependencyInjection/ControllerArgumentValueResolverPass.php b/DependencyInjection/ControllerArgumentValueResolverPass.php
@@ -12,6 +12,8 @@
 namespace Symfony\Component\HttpKernel\DependencyInjection;
 
 use Symfony\Component\DependencyInjection\Argument\IteratorArgument;
+use Symfony\Component\DependencyInjection\Argument\ServiceLocatorArgument;
+use Symfony\Component\DependencyInjection\Argument\TaggedIteratorArgument;
 use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
 use Symfony\Component\DependencyInjection\Compiler\PriorityTaggedServiceTrait;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
@@ -37,10 +39,24 @@ public function process(ContainerBuilder $container)
             return;
         }
 
-        $resolvers = $this->findAndSortTaggedServices('controller.argument_value_resolver', $container);
+        $definitions = $container->getDefinitions();
+        $namedResolvers = $this->findAndSortTaggedServices(new TaggedIteratorArgument('controller.pinned_value_resolver', 'name', needsIndexes: true), $container);
+        $resolvers = $this->findAndSortTaggedServices(new TaggedIteratorArgument('controller.argument_value_resolver', 'name', needsIndexes: true), $container);
+
+        foreach ($resolvers as $name => $resolverReference) {
+            $id = (string) $resolverReference;
+
+            if ($definitions[$id]->hasTag('controller.pinned_value_resolver')) {
+                unset($resolvers[$name]);
+            } else {
+                $namedResolvers[$name] ??= clone $resolverReference;
+            }
+        }
+
+        $resolvers = array_values($resolvers);
 
         if ($container->getParameter('kernel.debug') && class_exists(Stopwatch::class) && $container->has('debug.stopwatch')) {
-            foreach ($resolvers as $resolverReference) {
+            foreach ($resolvers + $namedResolvers as $resolverReference) {
                 $id = (string) $resolverReference;
                 $container->register("debug.$id", TraceableValueResolver::class)
                     ->setDecoratedService($id)
@@ -51,6 +67,7 @@ public function process(ContainerBuilder $container)
         $container
             ->getDefinition('argument_resolver')
             ->replaceArgument(1, new IteratorArgument($resolvers))
+            ->setArgument(2, new ServiceLocatorArgument($namedResolvers))
         ;
     }
 }
diff --git a/Exception/ResolverNotFoundException.php b/Exception/ResolverNotFoundException.php
@@ -0,0 +1,33 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\HttpKernel\Exception;
+
+class ResolverNotFoundException extends \RuntimeException
+{
+    /**
+     * @param string[] $alternatives
+     */
+    public function __construct(string $name, array $alternatives = [])
+    {
+        $msg = sprintf('You have requested a non-existent resolver "%s".', $name);
+        if ($alternatives) {
+            if (1 === \count($alternatives)) {
+                $msg .= ' Did you mean this: "';
+            } else {
+                $msg .= ' Did you mean one of these: "';
+            }
+            $msg .= implode('", "', $alternatives).'"?';
+        }
+
+        parent::__construct($msg);
+    }
+}
diff --git a/Tests/Controller/ArgumentResolverTest.php b/Tests/Controller/ArgumentResolverTest.php
