Merge pull request #87 from moufmouf/ID_class

Adding an ID PHP class to map ID GraphQL type easily

Author: moufmouf

docs/mutations.md

@@ -0,0 +1,28 @@
+---
+id: mutations
+title: Writing mutations
+sidebar_label: Mutations
+---
+
+In GraphQL-Controllers, mutations are created [just like queries](my_first_query.md).
+
+To create a mutation, you annotate a method in a controller with the `@Mutation` annotation.
+
+Here is a sample of a "saveProduct" query:
+
+```php
+namespace App\Controllers;
+
+use TheCodingMachine\GraphQL\Controllers\Annotations\Mutation;
+
+class ProductController
+{
+    /**
+     * @Mutation
+     */
+    public function saveProduct(int $id, string $name, ?float $price = null): Product
+    {
+        // Some code that saves a product.
+    }
+}
+```

docs/my_first_query.md

@@ -28,27 +28,26 @@ class MyController
 }
 ```
 
-- The `MyController` class does not need to extend any base class. For GraphQL-Controllers, a controller is simply a
-  simple class.
+- The `MyController` class does not need to extend any base class. For GraphQL-Controllers, a controller can be any
+  class.
 - The query method is annotated with a `@Query` annotation
 - The `MyController` class must be in the controllers namespace. You configured this namespace when you installed 
-GraphqlControllers. By default, in Symfony, the controllers namespace is `App\Controller`.
+GraphQL-Controllers. By default, in Symfony, the controllers namespace is `App\Controller`.
 
 <div class="alert alert-warning"><strong>Heads up!</strong> The <code>MyController</code> class must exist in the container of your 
-application and the container identifier MUST be the fully qualified class name.</div> 
-
-<div class="alert alert-info">If you are using the Symfony bundle (or a framework with autowiring like Laravel), this 
+application and the container identifier MUST be the fully qualified class name.<br/><br/>
+If you are using the Symfony bundle (or a framework with autowiring like Laravel), this 
 is usually not an issue as the container will automatically create the controller entry if you do not explicitly 
-declare it.</div>
+declare it.</div> 
 
 ## Testing the query
 
-By default, the GraphQL endpoint is "/graphql".
+By default, the GraphQL endpoint is "/graphql". You can send HTTP requests to this endpoint and get responses.
 
 The easiest way to test a GraphQL endpoint is to use [GraphiQL](https://github.com/graphql/graphiql) or 
 [Altair](https://altair.sirmuel.design/) test clients.
 
-These clients come with Chrome and Firefox plugins.
+These clients are available as Chrome or Firefox plugins.
 
 <div class="alert alert-info"><strong>Symfony users:</strong> If you are using the Symfony bundle, GraphiQL is also directly embedded.
 Simply head to <code>http://[path-to-my-app]/graphiql</code></div>
@@ -180,7 +179,7 @@ We are now ready to run our test query:
 <td style="width:50%">
 <strong>Query</strong>
 <pre><code>{
-  products {
+  product(id: 42) {
     name
   }
 }</code></pre>
@@ -189,11 +188,9 @@ We are now ready to run our test query:
 <strong>Answer</strong>
 <pre><code class="hljs css language-json">{
   "data": {
-    "products": [
-      {
+    "product": {
         "name": "Mouf"
-      }
-    ]
+    }
   }
 }</code></pre>
 </td>
@@ -222,9 +219,9 @@ If you have never worked with annotations before, here are a few things you shou
   use TheCodingMachine\GraphQL\Controllers\Annotations\Query;
   ```
 - Doctrine Annotations are hugely popular and used in many other libraries. They are widely supported in PHP IDEs.
-  We highly recommend you add support for Doctrine annotations in your preferred IDE:
-   - use [*PHP Annotations* if you use PHPStorm](https://plugins.jetbrains.com/plugin/7320-php-annotations)
-   - use [*Doctrine plugin* if you use Eclipse](https://marketplace.eclipse.org/content/doctrine-plugin)
+  We highly recommend you add support for Doctrine annotations in your favorite IDE:
+   - use [*"PHP Annotations"* if you use PHPStorm](https://plugins.jetbrains.com/plugin/7320-php-annotations)
+   - use [*"Doctrine plugin"* if you use Eclipse](https://marketplace.eclipse.org/content/doctrine-plugin)
    - Netbeans has native support
    - ...
 

docs/type_mapping.md

@@ -0,0 +1,133 @@
+---
+id: type_mapping
+title: Type mapping
+sidebar_label: Type mapping
+---
+
+The job of GraphQL-Controllers is to create GraphQL types from PHP types.
+
+Internally, GraphQL-Controllers uses a "type mapper".
+
+## Mapping a PHP class to a GraphQL type
+
+The ["my first query"](my_first_query.md) documentation page 
+already explains how to use the `@Type` annotation to map a PHP class to a GraphQL type. Please refer to this documentation
+for class mapping
+
+## Mapping of scalar types
+
+Scalar PHP types can be type-hinted to the corresponding GraphQL types:
+
+- string
+- int
+- bool
+- float
+
+## Mapping of ID type
+
+GraphQL comes with a native "ID" type. PHP has no such type.
+
+If you want to expose an "ID" type in your GraphQL model, you have 2 solutions:
+
+### Solution 1: force the outputType
+
+```php
+/**
+ * @Field(outputType="ID")
+ */
+public function getId(): string
+{
+
+}
+```
+
+Using the "outputType" attribute of the `@Field` annotation, you can force the output type to "ID".
+You can learn more about [forcing output types in the "custom output types" documentation](custom_output_types.md).
+
+### Solution 2: use the "ID" class
+
+```php
+use TheCodingMachine\GraphQL\Controllers\Types\ID;
+
+/**
+ * @Field
+ */
+public function getId(): ID
+{
+
+}
+```
+
+Note that you can also use the "ID" class as an input type:
+
+```php
+use TheCodingMachine\GraphQL\Controllers\Types\ID;
+
+/**
+ * @Mutation
+ */
+public function save(ID $id, string $name): Product
+{
+
+}
+```
+
+## Mapping of dates
+
+Out of the box, GraphQL does not have a `DateTime` type, but we took the liberty to add one, with sensible defaults.
+
+When used as an output type (i.e. in a "return type"), `DateTimeImmutable` or `DateTimeInterface` PHP classes are 
+automatically mapped to this `DateTime` GraphQL type.
+
+```php
+/**
+ * @Field
+ */
+public function getDate(): \DateTimeInterface
+{
+
+}
+```
+
+The "date" field will be of type "DateTime". In the returned JSON response to a query, the date is formatted as a string
+in the ISO8601 format (aka ATOM format).
+
+When used in an "input type" (i.e. in arguments of a method), the <code>DateTime</code> PHP class is not supported. 
+Only the <code>DateTimeImmutable</code> PHP class is mapped. 
+
+<div class="alert alert-success">This is ok:</div>
+
+```php
+/**
+ * @Query
+ * @return Product[]
+ */
+public function getProducts(\DateTimeImmutable $fromDate): array
+{
+
+}
+```
+
+<div class="alert alert-error">But <code>DateTime</code> input type is not supported:</div>
+
+```php
+/**
+ * @Query
+ * @return Product[]
+ */
+public function getProducts(\DateTime $fromDate): array // BAD
+{
+
+}
+```
+
+
+
+TODO: ID
+
+TODO: Union type
+
+TODO: External type
+TODO: Extend class
+TODO: Sourcefield (other doc)
+

src/FieldsBuilder.php

@@ -19,6 +19,7 @@
 use TheCodingMachine\GraphQL\Controllers\Mappers\CannotMapTypeExceptionInterface;
 use TheCodingMachine\GraphQL\Controllers\Reflection\CachedDocBlockFactory;
 use TheCodingMachine\GraphQL\Controllers\Types\CustomTypesRegistry;
+use TheCodingMachine\GraphQL\Controllers\Types\ID;
 use TheCodingMachine\GraphQL\Controllers\Types\TypeResolver;
 use TheCodingMachine\GraphQL\Controllers\Types\UnionType;
 use Iterator;
@@ -654,19 +655,23 @@ private function toGraphQlType(Type $type, ?GraphQLType $subType, bool $mapToInp
             return GraphQLType::float();
         } elseif ($type instanceof Object_) {
             $fqcn = (string) $type->getFqsen();
-            if ($fqcn === '\\DateTimeImmutable' || $fqcn === '\\DateTimeInterface') {
-                return DateTimeType::getInstance();
-            } elseif ($fqcn === '\\'.UploadedFileInterface::class) {
-                return CustomTypesRegistry::getUploadType();
-            } elseif ($fqcn === '\\DateTime') {
-                throw new GraphQLException('Type-hinting a parameter against DateTime is not allowed. Please use the DateTimeImmutable type instead.');
-            }
-
-            $className = ltrim($type->getFqsen(), '\\');
-            if ($mapToInputType) {
-                return $this->typeMapper->mapClassToInputType($className);
-            } else {
-                return $this->typeMapper->mapClassToInterfaceOrType($className, $subType);
+            switch ($fqcn) {
+                case '\\DateTimeImmutable':
+                case '\\DateTimeInterface':
+                    return DateTimeType::getInstance();
+                case '\\'.UploadedFileInterface::class:
+                    return CustomTypesRegistry::getUploadType();
+                case '\\DateTime':
+                    throw new GraphQLException('Type-hinting a parameter against DateTime is not allowed. Please use the DateTimeImmutable type instead.');
+                case '\\'.ID::class:
+                    return GraphQLType::id();
+                default:
+                    $className = ltrim($type->getFqsen(), '\\');
+                    if ($mapToInputType) {
+                        return $this->typeMapper->mapClassToInputType($className);
+                    } else {
+                        return $this->typeMapper->mapClassToInterfaceOrType($className, $subType);
+                    }
             }
         } elseif ($type instanceof Array_) {
             return GraphQLType::listOf(GraphQLType::nonNull($this->toGraphQlType($type->getValueType(), $subType, $mapToInputType)));

src/QueryField.php

@@ -5,14 +5,19 @@
 
 use function get_class;
 use GraphQL\Type\Definition\FieldDefinition;
+use GraphQL\Type\Definition\IDType;
 use GraphQL\Type\Definition\InputObjectType;
+use GraphQL\Type\Definition\InputType;
 use GraphQL\Type\Definition\ListOfType;
 use GraphQL\Type\Definition\NonNull;
 use GraphQL\Type\Definition\OutputType;
 use GraphQL\Type\Definition\ScalarType;
 use GraphQL\Type\Definition\Type;
+use InvalidArgumentException;
+use function is_array;
 use TheCodingMachine\GraphQL\Controllers\Hydrators\HydratorInterface;
 use TheCodingMachine\GraphQL\Controllers\Types\DateTimeType;
+use TheCodingMachine\GraphQL\Controllers\Types\ID;
 
 /**
  * A GraphQL field that maps to a PHP method automatically.
@@ -50,26 +55,7 @@ public function __construct(string $name, OutputType $type, array $arguments, ?c
             foreach ($arguments as $name => $arr) {
                 $type = $arr['type'];
                 if (isset($args[$name])) {
-                    $val = $args[$name];
-
-                    $type = $this->stripNonNullType($type);
-                    if ($type instanceof ListOfType) {
-                        $subtype = $this->stripNonNullType($type->getWrappedType());
-                        $val = array_map(function ($item) use ($subtype, $hydrator) {
-                            if ($subtype instanceof DateTimeType) {
-                                return new \DateTimeImmutable($item);
-                            } elseif ($subtype instanceof InputObjectType) {
-                                return $hydrator->hydrate($item, $subtype);
-                            }
-                            return $item;
-                        }, $val);
-                    } elseif ($type instanceof DateTimeType) {
-                        $val = new \DateTimeImmutable($val);
-                    } elseif ($type instanceof InputObjectType) {
-                        $val = $hydrator->hydrate($val, $type);
-                    } elseif (!$type instanceof ScalarType) {
-                        throw new \RuntimeException('Unexpected type: '.get_class($type));
-                    }
+                    $val = $this->castVal($args[$name], $type, $hydrator);
                 } elseif (array_key_exists('defaultValue', $arr)) {
                     $val = $arr['defaultValue'];
                 } else {
@@ -100,4 +86,33 @@ private function stripNonNullType(Type $type): Type
         }
         return $type;
     }
+
+    /**
+     * Casts a value received from GraphQL into an argument passed to a method.
+     *
+     * @param mixed $val
+     * @param InputType $type
+     * @return mixed
+     */
+    private function castVal($val, InputType $type, HydratorInterface $hydrator)
+    {
+        $type = $this->stripNonNullType($type);
+        if ($type instanceof ListOfType) {
+            if (!is_array($val)) {
+                throw new InvalidArgumentException('Expected GraphQL List but value passed is not an array.');
+            }
+            return array_map(function($item) use ($type, $hydrator) {
+                return $this->castVal($item, $type->getWrappedType(), $hydrator);
+            }, $val);
+        } elseif ($type instanceof DateTimeType) {
+            return new \DateTimeImmutable($val);
+        } elseif ($type instanceof IDType) {
+            return new ID($val);
+        } elseif ($type instanceof InputObjectType) {
+            return $hydrator->hydrate($val, $type);
+        } elseif (!$type instanceof ScalarType) {
+            throw new \RuntimeException('Unexpected type: '.get_class($type));
+        }
+        return $val;
+    }
 }

src/Types/ID.php

@@ -0,0 +1,35 @@
+<?php
+namespace TheCodingMachine\GraphQL\Controllers\Types;
+
+
+use InvalidArgumentException;
+use TheCodingMachine\GraphQL\Controllers\GraphQLException;
+
+/**
+ * A class that maps to the GraphQL ID type.
+ */
+class ID
+{
+    private $value;
+
+    public function __construct($value)
+    {
+        if (! is_scalar($value) && (! is_object($value) || ! method_exists($value, '__toString'))) {
+            throw new InvalidArgumentException('ID constructor cannot be passed a non scalar value.');
+        }
+        $this->value = $value;
+    }
+
+    /**
+     * @return bool|float|int|string
+     */
+    public function val()
+    {
+        return $this->value;
+    }
+
+    public function __toString()
+    {
+        return (string) $this->value;
+    }
+}