docs(mutations): Documentation for mutations (#718)

* Provide documentation for mutation plugins

* fix markdown

* update docs

* fix typos and other adjustments

* indent php code

Author: joaogarin

doc/SUMMARY.md

@@ -20,6 +20,8 @@
 
 * [Introduction](mutations/readme.md)
 * [Creating mutation plugins](mutations/creating-mutation-plugins.md)
+* [Writing custom mutations](mutations/custom-mutations.md)
+* [Writing custom validations](mutations/custom-validations.md)
 
 ## Authentication
 

doc/mutations/creating-mutation-plugins.md

@@ -1,7 +1,205 @@
-## Creating mutation plugins
+# Creating mutations for Entities
 
-WIP : For now for relevant information on custom mutations check the following links : 
+The graphql module uses the [Drupal plugin system](https://www.drupal.org/docs/8/api/plugin-api/plugin-api-overview) for a lot of the extensibility features of plugins. So a lot of the times when you want to extend the graphql module (for example when creating your own mutations) you will be using the plugin system and creating your own plugins.
 
--  https://www.amazeelabs.com/en/blog/extending-graphql-part-3-mutations
--  https://github.com/justinlevi/graphql_custom_mutation
--  http://joaogarin.com/posts/drupal-graphql-with-angular-and-apollo-part3
+## Why the automatic mutations were removed.
+
+In [this article](https://www.amazeelabs.com/en/blog/extending-graphql-part-3-mutations) it's well explained why automatic mutations were removed. But this, as stated in the article, does not mean that creating mutations is complicated. In fact, it's a simple task and one that might even provide with the extra flexibility you know and love from Drupal.
+
+## Mutations to create Drupal Entities
+
+One of the most common things you will want to do when with mutations is to create, update and delete entities. These CRUD operations on entities were made as simple as possible to implement and only require you to extend some generic classes provided by the graphql_core module.
+
+So let's have a look at how you can create a mutation from scratch to generate a new entity of type node, and in this case a new article. You can refer to the [Examples](https://github.com/drupal-graphql/graphql-examples) repository to look at some other examples as well for how to create other kinds of mutations.
+
+### CreateArticle Plugin
+
+The first step to create a mutation is to make the plugin. The graphql module provides a base class for creating new entities called `CreateEntityBase`. You should implement a plugin that extends this class when you want to create an entity.
+
+Let's look at what the code for this plugin looks like :
+
+```
+<?php
+
+namespace Drupal\graphql_examples\Plugin\GraphQL\Mutations;
+use Drupal\graphql\Annotation\GraphQLMutation;
+use Drupal\graphql\GraphQL\Execution\ResolveContext;
+use Drupal\graphql_core\Plugin\GraphQL\Mutations\Entity\CreateEntityBase;
+use GraphQL\Type\Definition\ResolveInfo;
+
+/**
+ * Simple mutation for creating a new article node.
+ *
+ * @GraphQLMutation(
+ *   id = "create_article",
+ *   entity_type = "node",
+ *   entity_bundle = "article",
+ *   secure = true,
+ *   name = "createArticle",
+ *   type = "EntityCrudOutput!",
+ *   arguments = {
+ *     "input" = "ArticleInput"
+ *   }
+ * )
+ */
+class CreateArticle extends CreateEntityBase {
+
+  /**
+   * {@inheritdoc}
+   */
+  protected function extractEntityInput(
+    $value,
+    array $args,
+    ResolveContext $context,
+    ResolveInfo $info
+  ) {
+    return [
+      'title' => $args['input']['title'],
+      'body' => $args['input']['body'],
+    ];
+  }
+
+}
+```
+
+We can see a couple things in this code that are particularly interesting :
+
+### Namespacing and folder structure
+
+The first thing we need to do when implementing the plugin is to give it a namespace, in this case we can see we use `graphql_examples`, you should replace this by your own module name.
+
+Make sure that this plugin lives inside `{{module_name}}//src/Plugin/GraphQL`
+
+### GraphQLMutation annotations
+
+The graphql module uses anotations for classes in order to have some information define the mutation in a simple way, things like :
+
+- id - The id of the mutation.
+- entity_type - The type of entity that is going to be created from this mutation (only important for when extending CreateEntityBase mutations)
+- entity_bundle - The bundle of the entity that is going to be created
+- secure - Fields that are not marked secure are automatically blocked in untrusted environments. For example there is a field that allows to fetch content from a remote url, which would basically turn your website into a proxy for anybody. This field will only work with a certain user permission or in persisted queries, where we are in control of what they do. The other way around, a field that is marked as secure doesn't allow any operations drupal itself wouldn't.
+- name - The name for the mutation. This name is what you will use when calling the mutation.
+- type - the "type" is the returned type by the mutation. In the example above the mutation returns a "EntityCrudOutput" type which is provided by the graphql module itself.
+- arguments - The arguments passed to the mutation. These are the fields for the entity you want to create, in the case above we are passing one argument called "Input" of type "ArticleInput". We will look at InputTypes afterwards. But essentially since graphql is strictly typed we want to provide information for types for each field we pass to the mutation we can do that using "InputTypes".
+
+### extractEntityInput method
+
+There is one method you should always implement when doing mutations, that is the `extractEntityInput` method which will be sort of a mapping between the arguments you pass to the mutation and the fields that drupal expects to receive for the entity being created.
+
+We can see we are assigning the `title` that we are passing in the input (we will look at the ArticleInput after) to the title property in the entity, same for the `body`.
+
+## Mutations to update Drupal Entities
+
+Let's continue with our article example. In this case we implement a mutation to update a given article. Because we are updating a particular entity and we need to know which entity it is, we will need to provide the plugin annotation with something extra, an Id for the entity.
+
+```
+<?php
+
+namespace Drupal\graphql_examples\Plugin\GraphQL\Mutations;
+use Drupal\graphql\Annotation\GraphQLMutation;
+use Drupal\graphql\GraphQL\Execution\ResolveContext;
+use Drupal\graphql_core\Plugin\GraphQL\Mutations\Entity\UpdateEntityBase;
+use GraphQL\Type\Definition\ResolveInfo;
+
+/**
+ * Simple mutation for updating an existing article node.
+ *
+ * @GraphQLMutation(
+ *   id = "update_article",
+ *   entity_type = "node",
+ *   entity_bundle = "article",
+ *   secure = true,
+ *   name = "updateArticle",
+ *   type = "EntityCrudOutput!",
+ *   arguments = {
+ *     "id" = "String",
+ *     "input" = "ArticleInput"
+ *   }
+ * )
+ */
+class UpdateArticle extends UpdateEntityBase {
+
+  /**
+   * {@inheritdoc}
+   */
+  protected function extractEntityInput(
+    $value,
+    array $args,
+    ResolveContext $context,
+    ResolveInfo $info
+  ) {
+    return array_filter([
+      'title' => $args['input']['title'],
+      'body' => $args['input']['body'],
+    ]);
+  }
+
+}
+```
+
+The first thing we noticed is we are now using `UpdateEntityBase` instead of "CreateEntityBase" as our parent class,
+we can also see that we use the same argument "Input" as above but we also have another argument called `id`. The Graphql Module will be smart enough to use that id to match to the right entity.
+
+## Mutations to Delete Drupal Entities
+
+The only thing left now is really to delete the entity right? This is the simplest type of operation out of the 3, because we only need to give graphql the `id`, it will check if we can access that type of operation and if so delete the entity with the id we give to it. So let's look at how the plugin looks like
+
+```
+<?php
+
+namespace Drupal\graphql_examples\Plugin\GraphQL\Mutations;
+use Drupal\graphql_core\Plugin\GraphQL\Mutations\Entity\DeleteEntityBase;
+
+/**
+ * Simple mutation for deleting an article node.
+ *
+ * @GraphQLMutation(
+ *   id = "delete_article",
+ *   entity_type = "node",
+ *   entity_bundle = "article",
+ *   secure = true,
+ *   name = "deleteArticle",
+ *   type = "EntityCrudOutput!",
+ *   arguments = {
+ *     "id" = "String"
+ *   }
+ * )
+ */
+class DeleteArticle extends DeleteEntityBase {
+}
+```
+
+We extend the `DeleteEntityBase` class and only require one argument: the id of the entity we want to delete. Additionally we add the required annotations as we previously did for the other mutations.
+
+## ArticleInput
+
+We know from the examples above that we need to define the arguments for mutations. Similar to how a function, mutations receive arguments that can be used to do whatever the mutation needs to do to work. In order for graphql to know information about the arguments we create an `InputType`. The ArticleInput that we used above looks like this :
+
+```
+<?php
+
+namespace Drupal\graphql_examples\Plugin\GraphQL\InputTypes;
+use Drupal\graphql\Plugin\GraphQL\InputTypes\InputTypePluginBase;
+
+/**
+ * The input type for article mutations.
+ *
+ * @GraphQLInputType(
+ *   id = "article_input",
+ *   name = "ArticleInput",
+ *   fields = {
+ *     "title" = "String",
+ *     "body" = {
+ *        "type" = "String",
+ *        "nullable" = "TRUE"
+ *     }
+ *   }
+ * )
+ */
+class ArticleInput extends InputTypePluginBase {
+}
+```
+
+We can see again that we namespace this plugin to our module name, in this case `graphql_examples` should be replaced by your own module name. This file should live inside `{{module_name}}/src/Plugin/GraphQL/InputTypes/ArticleInput.php`
+
+We can also see above that we only use annotations here to define the arguments inside the `fields` property. So we know that it receives a `title` and that's a "String" and we also receive a `body` which is also a `String`.

doc/mutations/custom-mutations.md

@@ -0,0 +1,81 @@
+# The MutationPluginBase plugin
+
+Not all mutations are directly related to an entity, and often you might need to perform operations on a mutation that are not necessarily creating, updating or deleting an entity in Drupal. For these cases you can use the `MutationPluginBase` plugin and extend that instead of extending the `CreateEntityBase` as we saw on _Creating mutations for Entities_.
+
+The mutation itself wouldn't be too different from what we did previously, you can see an example in the [Examples repo](https://github.com/drupal-graphql/graphql-examples/blob/master/src/Plugin/GraphQL/Mutations/FileUpload.php) of a file upload mutation.
+
+## Resolve method
+
+One important method of the MutationPluginBase is the resolve method where we, similar to our "extractEntityInput" above, get access to the arguments passed to the mutation and we can then perform the operation we want on Drupal.
+
+Let's look at an example that will perform an operation of buying a car. The operation itself exists on a service so it's not really important to look at the details of that operation, but what is important is that in the resolve method we take the `car` from our arguments (defined in the annotation as seen above) and we call our `garage` service and pass it the car :
+
+```
+<?php
+
+namespace Drupal\graphql_plugin_test\Plugin\GraphQL\Mutations;
+use Drupal\Core\DependencyInjection\DependencySerializationTrait;
+use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
+use Drupal\graphql\GraphQL\Execution\ResolveContext;
+use Drupal\graphql\Plugin\GraphQL\Mutations\MutationPluginBase;
+use Drupal\graphql_plugin_test\GarageInterface;
+use Symfony\Component\DependencyInjection\ContainerInterface;
+use GraphQL\Type\Definition\ResolveInfo;
+
+/**
+* A test mutation.
+*
+* @GraphQLMutation(
+*   id = "buy_car",
+*   secure = true,
+*   name = "buyCar",
+*   type = "Car",
+*   arguments = {
+*     "car" = "CarInput!"
+*   }
+* )
+*/
+class BuyCar extends MutationPluginBase implements ContainerFactoryPluginInterface {
+
+  use DependencySerializationTrait;
+
+  /**
+    * The garage.
+    *
+    * @var \Drupal\graphql_plugin_test\GarageInterface
+    */
+  protected $garage;
+
+  /**
+    * {@inheritdoc}
+    */
+  public static function create(ContainerInterface $container, array $configuration, $pluginId, $pluginDefinition) {
+    return new static($configuration, $pluginId, $pluginDefinition, $container->get('graphql_test.garage'));
+  }
+
+  /**
+    * BuyCar constructor.
+    *
+    * @param array $configuration
+    *   The plugin configuration array.
+    * @param string $pluginId
+    *   The plugin id.
+    * @param mixed $pluginDefinition
+    *   The plugin definition array.
+    * @param \Drupal\graphql_plugin_test\GarageInterface $garage
+    *   The garage service.
+    */
+  public function __construct(array $configuration, $pluginId, $pluginDefinition, GarageInterface $garage) {
+    parent::__construct($configuration, $pluginId, $pluginDefinition);
+    $this->garage = $garage;
+  }
+  /**
+    * {@inheritdoc}
+    */
+  public function resolve($value, array $args, ResolveContext $context, ResolveInfo $info) {
+    return $this->garage->insertVehicle($args['car']);
+  }
+}
+```
+
+This example was taken from the [a test](https://github.com/drupal-graphql/graphql/blob/188be525a007f385a3d3c4f8d2900b62a0150a5f/tests/modules/graphql_plugin_test/src/Plugin/GraphQL/Mutations/BuyCar.php) inside the graphql repository. Inside the resolve method it could be doing other things.

doc/mutations/custom-validations.md

@@ -0,0 +1,67 @@
+# Providing custom validation for mutations
+
+One aspect that is important to consider when creating mutations is providing good error messages and validations. Often you will be connecting these mutations to forms or other types of UI that should give the user clear indication of what went wrong. Access checks and permissions are also important to consider when creating mutations for your entities.
+
+## CreateEntitybase plugin access
+
+The `CreateEntityBase` plugin does a entity access check in it's resolveOutput method, so it will validate if a user is trying to create an entity it does not have access to and fail if that happens with a message : **"You do not have the necessary permissions to create entities of this type."**
+
+However you might have some other logic you want to perform, for example check that a user has done something else before he can perform this action, some kind of custom validation or a simple field access check, so that maybe a user that has no access to a particular field give his role fails accordingly.
+
+You can make custom validations by implementing your own `resolveOutput` method inside your mutation.
+
+## Custom validations - errors and violations
+
+Graphql mutations by default return 3 things :
+
+- data - The data that was returned by the mutation. what the consumer of the mutation asked for when running it (if successful)
+- errors - If an error occurred in Drupal (an exception) it will be added to the errors array.
+- violations - Violations are a useful way to provide error messages to users, nothing "crashed" but something went wrong and the user can't do the operation. Maybe he has no access or something else.
+
+### Adding custom information to errors
+
+To add things to the errors for example when creating an entity you can return a new `EntityCrudOutputWrapper`, e.g. :
+
+```
+if (!$entity->access('create')) {
+     return new EntityCrudOutputWrapper(NULL, NULL, [
+       $this->t('You do not have the necessary permissions to create entities of this type.'),
+     ]);
+}
+```
+
+In this case if the user has no access to create on this entity its going to fail. You can make your own logic inside resolve or resolveOutput to output your own information and logic to users.
+
+### Adding custom violations
+
+To add violations the process is very similar, you need to return a new `EntityCrudOutputWrapper`, you can decide based on your own situation if the entity should or not be returned (or if even should or not be processed and created) but the second argument to this `EntityCrudOutputWrapper` where we passed NULL previously is a `Violations` array of type `ConstraintViolationList` from Symphony. Check the [Drupal information on ConstraintViolationList](https://api.drupal.org/api/drupal/vendor%21symfony%21validator%21ConstraintViolationList.php/8.2.x) as well as [ConstraintViolation](https://api.drupal.org/api/drupal/vendor%21symfony%21validator%21ConstraintViolation.php/class/ConstraintViolation/8.2.x)
+
+There are a couple imporant pieces in ContrainstViolations you can use that are output by the graphql module to the user in the `violations` array :
+
+- code - Can indicate the type of violation
+- message - a clear message for the user of what went wrong
+- path - The path (field or other part) where the violation occurred
+
+See the following error for an example of a situation where a user tries updating an entity which he has access to but not a particular field :
+
+```
+{
+ "data": {
+   "addCredit": {
+     "entity": null,
+     "violations": [
+       {
+         "code": "403",
+         "message": "Access denied",
+         "path": "field_credit_status"
+       }
+     ],
+     "errors": [
+       "You do not have the necessary permissions to create some fields for this entity."
+     ]
+   }
+ }
+}
+```
+
+In this case it was decided to fail creating the entity `Credit` because the user does not have access to fields he is trying to create, but instead of only providing the generic message : _"You do not have the necessary permissions to create some fields for this entity."_ some extra information is added specifying which exact fields failed and why.