Prefetch refactor (#588)

* Make parts of graphqlite immutable

* Revert previous versions docs

* Refactor getters, PHPStan, codestyle

* Fix phpcbf's broken Cloneable

* Fix return types in docs

* Fix "test" class names used for resolvers

* Refactor GlobAnnotationsCache to be immutable

* Refactor prefetch

* Reformat

* Change docs for new prefetch

* Tests coverage for new Prefetch

* Reformat using cs-fix

* Fix failing test on --prefer-lowest

* Fix failing test on --prefer-lowest

* Add test for ParameterizedCallableResolverTest

Author: oprypkhantc

src/Annotations/Field.php

@@ -6,6 +6,10 @@
 
 use Attribute;
 
+use function trigger_error;
+
+use const E_USER_DEPRECATED;
+
 /**
  * @Annotation
  * @Target({"PROPERTY", "METHOD"})
@@ -44,6 +48,7 @@ class Field extends AbstractRequest
     public function __construct(array $attributes = [], string|null $name = null, string|null $outputType = null, string|null $prefetchMethod = null, string|array|null $for = null, string|null $description = null, string|null $inputType = null)
     {
         parent::__construct($attributes, $name, $outputType);
+
         $this->prefetchMethod = $prefetchMethod ?? $attributes['prefetchMethod'] ?? null;
         $this->description = $description ?? $attributes['description'] ?? null;
         $this->inputType = $inputType ?? $attributes['inputType'] ?? null;
@@ -54,6 +59,16 @@ public function __construct(array $attributes = [], string|null $name = null, st
         }
 
         $this->for = (array) $forValue;
+
+        if (! $this->prefetchMethod) {
+            return;
+        }
+
+        trigger_error(
+            "Using #[Field(prefetchMethod='" . $this->prefetchMethod . "')] on fields is deprecated in favor " .
+            "of #[Prefetch('" . $this->prefetchMethod . "')] \$data attribute on the parameter itself.",
+            E_USER_DEPRECATED,
+        );
     }
 
     /**

src/Annotations/Prefetch.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TheCodingMachine\GraphQLite\Annotations;
+
+use Attribute;
+use TheCodingMachine\GraphQLite\GraphQLRuntimeException;
+
+#[Attribute(Attribute::TARGET_PARAMETER)]
+class Prefetch implements ParameterAnnotationInterface
+{
+    /** @param string|(callable&array{class-string, string}) $callable */
+    public function __construct(public readonly string|array $callable)
+    {
+    }
+
+    public function getTarget(): string
+    {
+        // This is only needed for using #[Prefetch] as a Doctrine attribute, which it doesn't support.
+        throw new GraphQLRuntimeException();
+    }
+}

src/FieldsBuilder.php

@@ -17,10 +17,10 @@
 use ReflectionMethod;
 use ReflectionNamedType;
 use RuntimeException;
+use TheCodingMachine\GraphQLite\Parameters\ExpandsInputTypeParameters;
 use TheCodingMachine\GraphQLite\Parameters\InputTypeParameterInterface;
 use TheCodingMachine\GraphQLite\Parameters\ParameterInterface;
 
-use function array_filter;
 use function array_map;
 use function assert;
 use function ltrim;
@@ -99,6 +99,33 @@ private function resolveSelf(Type $type, ReflectionClass $reflectionClass): Type
         return $type;
     }
 
+    /**
+     * @param array<string, ParameterInterface> $parameters
+     *
+     * @return array<string, InputTypeParameterInterface>
+     */
+    public static function toInputParameters(array $parameters): array
+    {
+        $result = [];
+
+        foreach ($parameters as $name => $parameter) {
+            if ($parameter instanceof InputTypeParameterInterface) {
+                $result[$name] = $parameter;
+            }
+
+            if (! ($parameter instanceof ExpandsInputTypeParameters)) {
+                continue;
+            }
+
+            $result = [
+                ...$result,
+                ...$parameter->toInputTypeParameters(),
+            ];
+        }
+
+        return $result;
+    }
+
     /**
      * Maps an array of ParameterInterface to an array of field descriptors as accepted by Webonyx.
      *
@@ -108,9 +135,7 @@ private function resolveSelf(Type $type, ReflectionClass $reflectionClass): Type
      */
     public static function getInputTypeArgs(array $args): array
     {
-        $inputTypeArgs = array_filter($args, static function (ParameterInterface $parameter) {
-            return $parameter instanceof InputTypeParameterInterface;
-        });
+        $inputTypeArgs = self::toInputParameters($args);
 
         return array_map(static function (InputTypeParameterInterface $parameter): array {
             $desc = [

src/InputTypeUtils.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TheCodingMachine\GraphQLite;
+
+use Throwable;
+
+class InvalidCallableRuntimeException extends GraphQLRuntimeException
+{
+    public static function methodNotFound(string $className, string $methodName, Throwable|null $previous = null): self
+    {
+        return new self('Method ' . $className . '::' . $methodName . " wasn't found or isn't accessible.", 0, $previous);
+    }
+}

src/InvalidCallableRuntimeException.php

@@ -11,13 +11,22 @@
 
 class InvalidPrefetchMethodRuntimeException extends GraphQLRuntimeException
 {
+    /** @deprecated Remove with the removal of old #[Field(prefetchMethod)] */
     public static function methodNotFound(ReflectionMethod|ReflectionProperty $reflector, ReflectionClass $reflectionClass, string $methodName, ReflectionException $previous): self
     {
         throw new self('The @Field annotation in ' . $reflector->getDeclaringClass()->getName() . '::' . $reflector->getName() . ' specifies a "prefetch method" that could not be found. Unable to find method ' . $reflectionClass->getName() . '::' . $methodName . '.', 0, $previous);
     }
 
-    public static function prefetchDataIgnored(ReflectionMethod $annotationMethod, bool $isSecond): self
+    public static function fromInvalidCallable(
+        ReflectionMethod $reflector,
+        string $parameterName,
+        InvalidCallableRuntimeException $e,
+    ): self
     {
-        throw new self('The @Field annotation in ' . $annotationMethod->getDeclaringClass()->getName() . '::' . $annotationMethod->getName() . ' specifies a "prefetch method" but the data from the prefetch method is not gathered. The "' . $annotationMethod->getName() . '" method should accept a ' . ($isSecond ? 'second' : 'first') . ' parameter that will contain data returned by the prefetch method.');
+        return new self(
+            '#[Prefetch] attribute on parameter $' . $parameterName . ' in ' . $reflector->getDeclaringClass()->getName() . '::' . $reflector->getName() .
+            ' specifies a callable that is invalid: ' . $e->getMessage(),
+            previous: $e,
+        );
     }
 }

src/InvalidPrefetchMethodRuntimeException.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TheCodingMachine\GraphQLite\Mappers\Parameters;
+
+use phpDocumentor\Reflection\DocBlock;
+use phpDocumentor\Reflection\Type;
+use ReflectionMethod;
+use ReflectionParameter;
+use TheCodingMachine\GraphQLite\Annotations\ParameterAnnotations;
+use TheCodingMachine\GraphQLite\Annotations\Prefetch;
+use TheCodingMachine\GraphQLite\InvalidCallableRuntimeException;
+use TheCodingMachine\GraphQLite\InvalidPrefetchMethodRuntimeException;
+use TheCodingMachine\GraphQLite\ParameterizedCallableResolver;
+use TheCodingMachine\GraphQLite\Parameters\ParameterInterface;
+use TheCodingMachine\GraphQLite\Parameters\PrefetchDataParameter;
+
+use function assert;
+
+/**
+ * Handles {@see Prefetch} annotated parameters.
+ */
+class PrefetchParameterMiddleware implements ParameterMiddlewareInterface
+{
+    public function __construct(
+        private readonly ParameterizedCallableResolver $parameterizedCallableResolver,
+    )
+    {
+    }
+
+    public function mapParameter(ReflectionParameter $parameter, DocBlock $docBlock, Type|null $paramTagType, ParameterAnnotations $parameterAnnotations, ParameterHandlerInterface $next): ParameterInterface
+    {
+        $prefetch = $parameterAnnotations->getAnnotationByType(Prefetch::class);
+
+        if ($prefetch === null) {
+            return $next->mapParameter($parameter, $docBlock, $paramTagType, $parameterAnnotations);
+        }
+
+        $method = $parameter->getDeclaringFunction();
+
+        assert($method instanceof ReflectionMethod);
+
+        // Map callable specified by #[Prefetch] into a real callable and parse all of the GraphQL parameters.
+        try {
+            [$resolver, $parameters] = $this->parameterizedCallableResolver->resolve($prefetch->callable, $method->getDeclaringClass(), 1);
+        } catch (InvalidCallableRuntimeException $e) {
+            throw InvalidPrefetchMethodRuntimeException::fromInvalidCallable($method, $parameter->getName(), $e);
+        }
+
+        return new PrefetchDataParameter(
+            fieldName: $method->getName(),
+            resolver: $resolver,
+            parameters: $parameters,
+        );
+    }
+}

src/Mappers/Parameters/PrefetchParameterMiddleware.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TheCodingMachine\GraphQLite;
+
+use Psr\Container\ContainerInterface;
+use ReflectionClass;
+use ReflectionException;
+use ReflectionMethod;
+use TheCodingMachine\GraphQLite\Parameters\ParameterInterface;
+
+use function assert;
+use function is_callable;
+use function is_string;
+
+class ParameterizedCallableResolver
+{
+    public function __construct(
+        private readonly FieldsBuilder $fieldsBuilder,
+        private readonly ContainerInterface $container,
+    )
+    {
+    }
+
+    /**
+     * @param string|array{class-string, string} $callable
+     *
+     * @return array{callable, array<string, ParameterInterface>}
+     */
+    public function resolve(string|array $callable, string|ReflectionClass $classContext, int $skip = 0): array
+    {
+        if ($classContext instanceof ReflectionClass) {
+            $classContext = $classContext->getName();
+        }
+
+        // If string method is given, it's equivalent to [self::class, 'method']
+        if (is_string($callable)) {
+            $callable = [$classContext, $callable];
+        }
+
+        try {
+            $refMethod = new ReflectionMethod($callable[0], $callable[1]);
+        } catch (ReflectionException $e) {
+            throw InvalidCallableRuntimeException::methodNotFound($callable[0], $callable[1], $e);
+        }
+
+        // If method isn't static, then we should try to resolve the class name through the container.
+        if (! $refMethod->isStatic()) {
+            $callable = fn (...$args) => $this->container->get($callable[0])->{$callable[1]}(...$args);
+        }
+
+        assert(is_callable($callable));
+
+        // Map all parameters of the callable.
+        $parameters = $this->fieldsBuilder->getParameters($refMethod, $skip);
+
+        return [$callable, $parameters];
+    }
+}

src/ParameterizedCallableResolver.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TheCodingMachine\GraphQLite\Parameters;
+
+interface ExpandsInputTypeParameters
+{
+    /** @return array<string, InputTypeParameterInterface> */
+    public function toInputTypeParameters(): array;
+}