Add documentation about custom types, queries and mutations

Author: alanpoulain

core/graphql.md

@@ -129,6 +129,8 @@ final class BookCollectionResolver implements QueryCollectionResolverInterface
      */
     public function __invoke($collection, array $context)
     {
+        // Query arguments are in $context['args'].
+
         foreach ($collection as $book) {
             // Do something with the book.
         }
@@ -170,6 +172,8 @@ final class BookResolver implements QueryItemResolverInterface
      */
     public function __invoke($item, array $context)
     {
+        // Query arguments are in $context['args'].
+
         // Do something with the book.
         // Or fetch the book if it has not been retrieved.
 
@@ -235,6 +239,8 @@ Conversely, if you need to add custom arguments, make sure `id` is added among t
 - If you have added your [own custom types](#custom-types), you can use them directly for your arguments types (it's the case here for `DateTime`).
 - You can also add a custom description for your custom arguments. You can see the [field arguments documentation](https://webonyx.github.io/graphql-php/type-system/object-types/#field-arguments) for more options.
 
+The arguments you have defined or the default ones and their value will be in `$context['args']` of your resolvers.
+
 You custom queries will be available like this:
 
 ```graphql
@@ -284,6 +290,103 @@ mutation DeleteBook($id: ID!, $clientMutationId: String!) {
 }
 ```
 
+### Custom mutations
+
+Creating custom mutations is like creating the [custom queries](#custom-queries).
+
+Create your resolver:
+
+```php
+<?php
+
+namespace App\Resolver;
+
+use ApiPlatform\Core\GraphQl\Resolver\MutationResolverInterface;
+use App\Model\Book;
+
+final class BookMutationResolver implements MutationResolverInterface
+{
+    /**
+     * @param Book|null $item
+     *
+     * @return Book
+     */
+    public function __invoke($item, array $context)
+    {
+        // Mutation input arguments are in $context['args']['input'].
+
+        // Do something with the book.
+        // Or fetch the book if it has not been retrieved.
+
+        // The returned item will pe persisted.
+        return $item;
+    }
+}
+```
+
+As you can see, depending on how you will define this resolver in the resource, the item is retrieved or not.
+Likewise, if you don't want your item to be persisted by API Platform, you can return `null` instead of the mutated item.
+Don't forget the resolver is a service and you can inject the dependencies you want.
+
+If you don't use autoconfiguration, add the tag `api_platform.graphql.mutation_resolver` to the resolver service.
+
+Now in your resource:
+
+```php
+<?php
+
+namespace App\Model;
+
+use ApiPlatform\Core\Annotation\ApiResource;
+use App\Resolver\BookMutationResolver;
+
+/**
+ * @ApiResource(graphql={
+ *     "mutation"={
+ *         "mutation"=BookMutationResolver::class
+ *     },
+ *     "withCustomArgsMutation"={
+ *         "mutation"=BookMutationResolver::class,
+ *         "args"={
+ *             "sendMail"={"type"="Boolean!", "description"="Send a mail?"}
+ *         }
+ *     }
+ * })
+ */
+class Book
+{
+    // ...
+}
+```
+
+As the custom queries, you can define your own arguments if you don't want to use the default ones (extracted from your resource).
+The only difference with them is that, even if you define your own arguments, the `clientMutationId` will always be set.
+
+The arguments will be in `$context['args']['input']` of your resolvers.
+
+You custom mutations will be available like this:
+
+```graphql
+{
+  mutation {
+    mutationBook(input: {id: "/books/18", title: "The Fitz and the Fool"}) {
+      book {
+        title
+      }
+    }
+  }
+
+  mutation {
+    withCustomArgsMutationBook(input: {sendMail: true, clientMutationId: "myId}) {
+      book {
+        title
+      }
+      clientMutationId
+    }
+  }
+}
+```
+
 ## Filters
 
 Filters are supported out-of-the-box. Follow the [filters](filters.md) documentation and your filters will be available as arguments of queries.