Merge pull request #14 from moufmouf/fixed_return_types

Adding the ability to specify the GraphQL return type manually

Author: moufmouf

README.md

@@ -10,8 +10,6 @@
 GraphQL controllers
 ===================
 
-**Work in progress, no stable release yet**
-
 A utility library on top of `Youshido/graphql` library.
 
 This library allows you to write your GraphQL queries in simple to write controllers:
@@ -92,12 +90,43 @@ public function users(int $limit, int $offset): array
 }
 ```
 
-Type-hinting against objects
-----------------------------
+Type-hinting against objects (automatic)
+----------------------------------------
 
 When you specify an object type-hint, graphql-controllers will delegate the object creation to an hydrator.
 You must pass this hydrator in parameter when building the `ControllerQueryProvider`.
 
+Type-hinting against objects (manually)
+---------------------------------------
+
+As an alternative, you can also manually specify the GraphqlType of your return type manually.
+
+```php
+/**
+ * @Query(returnType=UserListType::class)
+ */
+public function users(int $limit, int $offset)
+{
+    // Whatever the return type of the method, it will be managed as a GraphQL UserListType
+    // UserListType must implement Youshido's TypeInterface
+}
+```
+
+You can also specify the name of an entry in the container that resolves to the GraphQL type to be used.
+
+```php
+/**
+ * @Query(returnType="userListType")
+ */
+public function users(int $limit, int $offset)
+{
+    // The return type is fetched from the container. Expected name is "userListType"
+}
+```
+
+Note: for container discovery to work, you must pass the container when constructing the `ControllerQueryProvider` object.
+
+
 Troubleshooting
 ---------------
 

src/Annotations/AbstractRequest.php

@@ -0,0 +1,32 @@
+<?php
+
+
+namespace TheCodingMachine\GraphQL\Controllers\Annotations;
+
+
+abstract class AbstractRequest
+{
+    /**
+     * @var string|null
+     */
+    private $returnType;
+
+    /**
+     * @param mixed[] $attributes
+     */
+    public function __construct(array $attributes = [])
+    {
+        $this->returnType = $attributes['returnType'] ?? null;
+    }
+
+    /**
+     * Returns the GraphQL return type of the request (as a string).
+     * The string can represent the FQCN of the type or an entry in the container resolving to the GraphQL type.
+     *
+     * @return string|null
+     */
+    public function getReturnType(): ?string
+    {
+        return $this->returnType;
+    }
+}

src/Annotations/Mutation.php

@@ -5,7 +5,10 @@
 
 /**
  * @Annotation
+ * @Attributes({
+ *   @Attribute("returnType", type = "string"),
+ * })
  */
-class Mutation
+class Mutation extends AbstractRequest
 {
 }

src/Annotations/Query.php

@@ -5,7 +5,10 @@
 
 /**
  * @Annotation
+ * @Attributes({
+ *   @Attribute("returnType", type = "string"),
+ * })
  */
-class Query
+class Query extends AbstractRequest
 {
 }

src/ControllerQueryProvider.php

@@ -10,15 +10,19 @@
 use phpDocumentor\Reflection\Types\Mixed_;
 use phpDocumentor\Reflection\Types\Object_;
 use phpDocumentor\Reflection\Types\String_;
+use Psr\Container\ContainerInterface;
 use Roave\BetterReflection\Reflection\ReflectionClass;
 use Roave\BetterReflection\Reflection\ReflectionMethod;
 use Doctrine\Common\Annotations\Reader;
 use phpDocumentor\Reflection\Types\Integer;
+use TheCodingMachine\GraphQL\Controllers\Annotations\AbstractRequest;
 use TheCodingMachine\GraphQL\Controllers\Annotations\Logged;
 use TheCodingMachine\GraphQL\Controllers\Annotations\Mutation;
 use TheCodingMachine\GraphQL\Controllers\Annotations\Query;
 use TheCodingMachine\GraphQL\Controllers\Annotations\Right;
 use TheCodingMachine\GraphQL\Controllers\Reflection\CommentParser;
+use TheCodingMachine\GraphQL\Controllers\Registry\EmptyContainer;
+use TheCodingMachine\GraphQL\Controllers\Registry\Registry;
 use TheCodingMachine\GraphQL\Controllers\Security\AuthenticationServiceInterface;
 use TheCodingMachine\GraphQL\Controllers\Security\AuthorizationServiceInterface;
 use Youshido\GraphQL\Field\Field;
@@ -30,7 +34,6 @@
 use Youshido\GraphQL\Type\Scalar\IntType;
 use Youshido\GraphQL\Type\Scalar\StringType;
 use Youshido\GraphQL\Type\TypeInterface;
-use Youshido\GraphQL\Type\Union\UnionType;
 
 /**
  * A query provider that looks for queries in a "controller"
@@ -61,18 +64,23 @@ class ControllerQueryProvider implements QueryProviderInterface
      * @var AuthorizationServiceInterface
      */
     private $authorizationService;
+    /**
+     * @var ContainerInterface
+     */
+    private $registry;
 
     /**
      * @param object $controller
      */
-    public function __construct($controller, Reader $annotationReader, TypeMapperInterface $typeMapper, HydratorInterface $hydrator, AuthenticationServiceInterface $authenticationService, AuthorizationServiceInterface $authorizationService)
+    public function __construct($controller, Reader $annotationReader, TypeMapperInterface $typeMapper, HydratorInterface $hydrator, AuthenticationServiceInterface $authenticationService, AuthorizationServiceInterface $authorizationService, ?ContainerInterface $container = null)
     {
         $this->controller = $controller;
         $this->annotationReader = $annotationReader;
         $this->typeMapper = $typeMapper;
         $this->hydrator = $hydrator;
         $this->authenticationService = $authenticationService;
         $this->authorizationService = $authorizationService;
+        $this->registry = new Registry($container ?: new EmptyContainer());
     }
 
     /**
@@ -106,6 +114,7 @@ private function getFieldsByAnnotations(string $annotationName): array
             $standardPhpMethod = new \ReflectionMethod(get_class($this->controller), $refMethod->getName());
             // First, let's check the "Query" annotation
             $queryAnnotation = $this->annotationReader->getMethodAnnotation($standardPhpMethod, $annotationName);
+            /* @var $queryAnnotation AbstractRequest */
 
             if ($queryAnnotation !== null) {
                 $docBlock = new CommentParser($refMethod->getDocComment());
@@ -119,11 +128,16 @@ private function getFieldsByAnnotations(string $annotationName): array
 
                 $phpdocType = $typeResolver->resolve((string) $refMethod->getReturnType());
 
-                try {
-                    $type = $this->mapType($phpdocType, $refMethod->getDocBlockReturnTypes(), $standardPhpMethod->getReturnType()->allowsNull(), false);
-                } catch (TypeMappingException $e) {
-                    throw TypeMappingException::wrapWithReturnInfo($e, $refMethod);
+                if ($queryAnnotation->getReturnType()) {
+                    $type = $this->registry->get($queryAnnotation->getReturnType());
+                } else {
+                    try {
+                        $type = $this->mapType($phpdocType, $refMethod->getDocBlockReturnTypes(), $standardPhpMethod->getReturnType()->allowsNull(), false);
+                    } catch (TypeMappingException $e) {
+                        throw TypeMappingException::wrapWithReturnInfo($e, $refMethod);
+                    }
                 }
+
                 $queryList[] = new QueryField($methodName, $type, $args, [$this->controller, $methodName], $this->hydrator, $docBlock->getComment());
             }
         }

src/Registry/EmptyContainer.php

@@ -0,0 +1,22 @@
+<?php
+
+
+namespace TheCodingMachine\GraphQL\Controllers\Registry;
+
+use Psr\Container\ContainerInterface;
+
+/**
+ * An always empty container (to use as a stub for the Registry).
+ */
+class EmptyContainer implements ContainerInterface
+{
+    public function get($id)
+    {
+        throw NotFoundException::notFound($id);
+    }
+
+    public function has($id)
+    {
+        return false;
+    }
+}

src/Registry/NotFoundException.php

@@ -0,0 +1,14 @@
+<?php
+
+
+namespace TheCodingMachine\GraphQL\Controllers\Registry;
+
+use Psr\Container\NotFoundExceptionInterface;
+
+class NotFoundException extends \RuntimeException implements NotFoundExceptionInterface
+{
+    public static function notFound(string $id): NotFoundException
+    {
+        return new self('Could not find entry with ID / type with class "'.$id.'"');
+    }
+}

src/Registry/Registry.php

@@ -0,0 +1,106 @@
+<?php
+
+
+namespace TheCodingMachine\GraphQL\Controllers\Registry;
+
+use Psr\Container\ContainerExceptionInterface;
+use Psr\Container\ContainerInterface;
+use Psr\Container\NotFoundExceptionInterface;
+use TheCodingMachine\GraphQL\Controllers\Security\AuthorizationServiceInterface;
+use Youshido\GraphQL\Type\Object\AbstractObjectType;
+
+/**
+ * The role of the registry is to provide access to all GraphQL types.
+ * If the type is not found, it can be queried from the container, or if not in the container, it can be created from the Registry itself.
+ */
+class Registry implements ContainerInterface
+{
+
+    /**
+     * @var ContainerInterface
+     */
+    private $container;
+
+    /**
+     * @var AbstractObjectType[]
+     */
+    private $values = [];
+    /**
+     * @var null|AuthorizationServiceInterface
+     */
+    private $authorizationService;
+
+    /**
+     * @param ContainerInterface $container The proxied container.
+     * @param AuthorizationServiceInterface|null $authorizationService
+     */
+    public function __construct(ContainerInterface $container, AuthorizationServiceInterface $authorizationService = null)
+    {
+        $this->container = $container;
+        $this->authorizationService = $authorizationService;
+    }
+
+    /**
+     * Finds an entry of the container by its identifier and returns it.
+     *
+     * @param string $id Identifier of the entry to look for.
+     *
+     * @throws NotFoundExceptionInterface  No entry was found for **this** identifier.
+     * @throws ContainerExceptionInterface Error while retrieving the entry.
+     *
+     * @return mixed Entry.
+     */
+    public function get($id)
+    {
+        if (isset($this->values[$id])) {
+            return $this->values[$id];
+        }
+        if ($this->container->has($id)) {
+            return $this->container->get($id);
+        }
+
+        if (is_a($id, AbstractObjectType::class, true)) {
+            $this->values[$id] = new $id($this);
+            return $this->values[$id];
+        }
+
+        throw NotFoundException::notFound($id);
+    }
+
+    /**
+     * Returns true if the container can return an entry for the given identifier.
+     * Returns false otherwise.
+     *
+     * `has($id)` returning true does not mean that `get($id)` will not throw an exception.
+     * It does however mean that `get($id)` will not throw a `NotFoundExceptionInterface`.
+     *
+     * @param string $id Identifier of the entry to look for.
+     *
+     * @return bool
+     */
+    public function has($id)
+    {
+        if (isset($this->values[$id])) {
+            return true;
+        }
+        if ($this->container->has($id)) {
+            return true;
+        }
+
+        if (is_a($id, AbstractObjectType::class, true)) {
+            return true;
+        }
+
+        return false;
+    }
+
+    /**
+     * Returns the authorization service.
+     *
+     * @return AuthorizationServiceInterface|null
+     */
+    public function getAuthorizationService(): ?AuthorizationServiceInterface
+    {
+        return $this->authorizationService;
+    }
+}

tests/AggregateControllerQueryProviderTest.php

@@ -44,7 +44,7 @@ public function has($id)
         $aggregateQueryProvider = new AggregateControllerQueryProvider([ 'controller' ], $container, $reader, $this->getTypeMapper(), $this->getHydrator(), new VoidAuthenticationService(), new VoidAuthorizationService());
 
         $queries = $aggregateQueryProvider->getQueries();
-        $this->assertCount(1, $queries);
+        $this->assertCount(2, $queries);
 
         $mutations = $aggregateQueryProvider->getMutations();
         $this->assertCount(1, $mutations);