docs(composable): Document composable schemas and union/interface type resolvers. (#847)

Author: joaogarin

doc/SUMMARY.md

@@ -23,3 +23,7 @@
 ## Mutations
 
 * [Mutations](mutations/README.md)
+
+## Advanced
+
+* [Composable schemas](advanced/composable-schemas.md)

doc/advanced/composable-schemas.md

@@ -0,0 +1,116 @@
+# Splitting up the schema over multiple modules with composable schemas
+
+It is possible to split up the schema into separate parts so that you can enable certain functionality that is for example tied to a particular module only when that module is enabled.
+
+You can find a complete example [here](https://github.com/drupal-graphql/graphql/tree/8.x-4.x/examples) on how this can be done.
+
+If you have a complex system where certain modules are sometimes enabled / disabled and you want to make sure the API matches the functionality provided by those modules and also disable the API's that correspond to those modules when the modules are disabled splitting schemas into chunks is a good idea. This will keep the system organized and easy to read and look at.
+
+## Register a new Schema Extension
+
+A new schema extension can be inserted inside a new module so that it can extend a given schema (in the example bellow the schema `example`) with new fields and types. The `schema` key will tell which schema to attach these types to and the `id` key will be used to tell which files to pick up from when generating the schema.
+
+```php
+<?php
+namespace Drupal\graphql_examples\Plugin\GraphQL\SchemaExtension;
+use Drupal\graphql\GraphQL\ResolverBuilder;
+use Drupal\graphql\GraphQL\ResolverRegistryInterface;
+use Drupal\graphql\Plugin\GraphQL\SchemaExtension\SdlSchemaExtensionPluginBase;
+/**
+ * @SchemaExtension(
+ *   id = "example_extension",
+ *   name = "Example extension",
+ *   description = "A simple extension that adds node related fields.",
+ *   schema = "example"
+ * )
+ */
+class ExampleSchemaExtension extends SdlSchemaExtensionPluginBase {
+}
+```
+
+## Add new types and fields
+
+To add new types and fields to the schema create a file inside `/graphql/example_extension.base.graphqls` (as seen [here](https://github.com/drupal-graphql/graphql/blob/8.x-4.x/examples/graphql/example_extension.base.graphqls)) with the new types :
+
+```
+type Page {
+  id: Int!
+  title: String
+}
+```
+
+In this case we are creating a new type `Page`.
+
+## Change existing types or fields
+
+Normally a new module when enabled should also change or add more fields to an existing type. In that case create new file `/graphql/example_extension.extension.graphqls` as seen [here](https://github.com/drupal-graphql/graphql/blob/8.x-4.x/examples/graphql/example_extension.extension.graphqls)
+
+```
+extend type Query {
+  page(id: Int!): Page
+}
+```
+
+We are adding a new field inside the built-in `Query` type.
+
+## Add the resolvers
+
+We can now add our resolvers to the Extension class created previously so that our new fields actually resolve something :
+
+```php
+<?php
+namespace Drupal\graphql_examples\Plugin\GraphQL\SchemaExtension;
+use Drupal\graphql\GraphQL\ResolverBuilder;
+use Drupal\graphql\GraphQL\ResolverRegistryInterface;
+use Drupal\graphql\Plugin\GraphQL\SchemaExtension\SdlSchemaExtensionPluginBase;
+/**
+ * @SchemaExtension(
+ *   id = "example_extension",
+ *   name = "Example extension",
+ *   description = "A simple extension that adds node related fields.",
+ *   schema = "example"
+ * )
+ */
+class ExampleSchemaExtension extends SdlSchemaExtensionPluginBase {
+  /**
+   * {@inheritdoc}
+   */
+  public function registerResolvers(ResolverRegistryInterface $registry) {
+    $builder = new ResolverBuilder();
+    $this->addQueryFields($registry, $builder);
+    $this->addPageFields($registry, $builder);
+  }
+  /**
+   * @param \Drupal\graphql\GraphQL\ResolverRegistryInterface $registry
+   * @param \Drupal\graphql\GraphQL\ResolverBuilder $builder
+   */
+  protected function addPageFields(ResolverRegistryInterface $registry, ResolverBuilder $builder) {
+    $registry->addFieldResolver('Page', 'id',
+      $builder->produce('entity_id')
+        ->map('entity', $builder->fromParent())
+    );
+    $registry->addFieldResolver('Page', 'title',
+      $builder->compose(
+        $builder->produce('entity_label')
+          ->map('entity', $builder->fromParent()),
+        $builder->produce('uppercase')
+          ->map('string', $builder->fromParent())
+      )
+    );
+  }
+  /**
+   * @param \Drupal\graphql\GraphQL\ResolverRegistryInterface $registry
+   * @param \Drupal\graphql\GraphQL\ResolverBuilder $builder
+   */
+  protected function addQueryFields(ResolverRegistryInterface $registry, ResolverBuilder $builder) {
+    $registry->addFieldResolver('Query', 'page',
+      $builder->produce('entity_load')
+        ->map('type', $builder->fromValue('node'))
+        ->map('bundles', $builder->fromValue(['page']))
+        ->map('id', $builder->fromArgument('id'))
+    );
+  }
+}
+```
+
+Here we are only resolving the newly added fields. So that the functionality of adding the page to the API is all encapsulated in its own module.

doc/queries/nodes.md

@@ -36,7 +36,7 @@ Now we have an "Article" type in the schema with three fields `id`, `label` and
 
 ## Adding resolvers
 
-To add the resolvers we go to our schema implementation and call the appropriate data producers inside the `getResolverRegistry` method.
+To add the resolvers we go to our schema implementation and call the appropriate data producers inside the `getResolverRegistry` method. Because our types are extending a common `NodeInterface` we need to also tell what to resolve for a particular type, otherwise it could be an Article or a Page.
 
 ```php
 /**
@@ -48,32 +48,43 @@ protected function getResolverRegistry() {
     'Article' => ContextDefinition::create('entity:node')
       ->addConstraint('Bundle', 'article'),
   ]);
-  
+
+  // Tell GraphQL how to resolve types of a common interface.
+  $registry->addTypeResolver('NodeInterface', function ($value) {
+    if ($value instanceof NodeInterface) {
+      switch ($value->bundle()) {
+        case 'article': return 'Article';
+        case 'page': return 'Page';
+      }
+    }
+    throw new Error('Could not resolve content type.');
+  });
+
   $registry->addFieldResolver('Query', 'article',
     $builder->produce('entity_load')
       ->map('type', $builder->fromValue('node'))
       ->map('bundles', $builder->fromValue(['article']))
       ->map('id', $builder->fromArgument('id'))
     ]])
   );
-  
+
   $registry->addFieldResolver('Article', 'id',
     $builder->produce('entity_id')
       ->map('entity' => $builder->fromParent())
   );
-  
+
   $registry->addFieldResolver('Article', 'title',
     $builder->produce('entity_label')
       ->map('entity', $builder->fromParent())
   );
-  
+
   $registry->addFieldResolver('Article', 'creator',
     $builder->produce('property_path')
       ->map('type', $builder->fromValue('entity:node'))
       ->map('value', $builder->fromParent())
       ->map('path', $builder->fromValue('field_article_creator.value'))
   );
-  
+
   return $registry;
 }
 ```

doc/queries/routes.md

@@ -1,6 +1,6 @@
 # Querying routes
 
-A very powerful feature of Drupal is the ability to manage paths in entities and using path aliases to manage clean URL's. We can leverage data producers provided by the graphql module to query these paths from Drupal.
+A very powerful feature of Drupal is the ability to manage paths in entities and using path aliases to manage clean URL's. We can leverage data producers provided by the GraphQL module to query these paths from Drupal.
 
 In this section we will look at how we can load a node from it's URL.
 
@@ -29,7 +29,7 @@ interface NodeInterface {
 
 ```
 
-In this schema we can see that we can query a node by its route, that takes a parameter called "path". We also (similar to the test schema that comes with the module) have a "NodeInterface" and an "Article" type that implements that interface. That means our "Article" will be available inside a fragment in the NodeInterface type.
+In this schema we can see that we can query a node by its route, that takes a parameter called "path". We also (similar to the test schema that comes with the module) have a `NodeInterface` and an "Article" type that implements that interface. That means our "Article" will be available inside a fragment in the `NodeInterface` type.
 
 ## Adding resolvers
 
@@ -42,6 +42,17 @@ To add the resolvers we go to our schema implementation and call the appropriate
 protected function getResolverRegistry() {
   ...
 
+  // Tell GraphQL how to resolve types of a common interface.
+  $registry->addTypeResolver('NodeInterface', function ($value) {
+    if ($value instanceof NodeInterface) {
+      switch ($value->bundle()) {
+        case 'article': return 'Article';
+        case 'page': return 'Page';
+      }
+    }
+    throw new Error('Could not resolve content type.');
+  });
+
   $registry->addFieldResolver('Query', 'route', $builder->compose(
     $builder->produce('route_load')
       ->map('path', $builder->fromArgument('path')),

doc/starting/custom-schema.md

@@ -2,80 +2,20 @@
 
 The best way to start making a new schema is to take the example schema provided by the graphql_examples module in `/graphql/examples/` and copy all the files from the example module to a custom module of your own. By doing this you can then start adapting the schema to your needs including your own content types and making them available in the schema.
 
-## Clone the SdlSchemaTest (deprecated)
-
-First create your own module and call it `mydrupalgql`. Make sure you have a .info file inside the module to make sure drupal will know about this module (for more info see [Custom modules in drupal](https://www.drupal.org/docs/8/creating-custom-modules)).
-Then head to the graphql module folder and copy the content of `src/Plugin/GraphQL/Schema/SdlSchemaTest.php`.
-Inside `modules/mydrupalgql` create a file for your custom schema using this structure `src/Plugin/GraphQL/Schema/SdlSchemaMyDrupalGql.php` and paste the content of the previous file. Make sure to adapt the namespaces on the top of the file. In the end it should look something like this (some parts of the schema are marked with `...` for simplicity):
-
-```php
-
-namespace Drupal\mydrupalgql\Plugin\GraphQL\Schema;
-
-use Drupal\Core\Plugin\Context\ContextDefinition;
-use Drupal\graphql\GraphQL\ResolverBuilder;
-use Drupal\graphql\GraphQL\ResolverRegistry;
-use Drupal\graphql\Plugin\GraphQL\Schema\SdlSchemaPluginBase;
-
-/**
- * @Schema(
- *   id = "mydrupalgql",
- *   name = "My Drupal Graphql Schema"
- * )
- * @codeCoverageIgnore
- */
-class SdlSchemaMyDrupalGql extends SdlSchemaPluginBase {
-
-  /**
-   * {@inheritdoc}
-   */
-  protected function getSchemaDefinition() {
-    return <<<GQL
-      schema {
-        query: Query
-      }
+## Enable the custom schema
 
-      type Query {
-        article(id: Int!): Article
-        page(id: Int!): Page
-        node(id: Int!): NodeInterface
-        label(id: Int!): String
-      }
+Go back to the list of servers under `/admin/config/graphql` to create a new server for your custom schema. When creating the server choose the "My Drupal Graphql Schema" as the schema. After saving click "Explorer". This will take you to the "GraphiQL" page, where you can explore your custom schema.
 
-      type Article implements NodeInterface {
-        id: Int!
-        uid: String
-        title: String!
-        render: String
-      }
+## Adapt module to your needs
 
-      ...
+Inside `/graphql` you will find some files that are a common `.graphqls` file that your editor will likely pick up as GraphQL files already. They include the schema definition for your custom schema.
 
-      interface NodeInterface {
-        id: Int!
-      }
-GQL;
-  }
+### example.graphqls
 
-  /**
-   * {@inheritdoc}
-   */
-  protected function getResolverRegistry() {
-    $builder = new ResolverBuilder();
-    $registry = new ResolverRegistry([
-      'Article' => ContextDefinition::create('entity:node')
-        ->addConstraint('Bundle', 'article'),
-      'Page' => ContextDefinition::create('entity:node')
-        ->addConstraint('Bundle', 'page'),
-    ]);
+This is the main entry point for your schema. You can insert new types and fields into types here as needed for your use case. Simply adding new types and fields here will not affect the API right away, they will be available but will not yet resolve anything, as we didn't add any resolvers yet.
 
-    ...
+If your requirements are simple this file should be enough to get started.
 
-    return $registry;
-  }
-}
-```
+### Extensions
 
-## Enable the custom schema
-
-Go back to the list of servers under `/admin/config/graphql` to create a new server for your custom schema. When creating the server choose the "My Drupal Graphql Schema" as the schema. After saving click "Explorer". This will take you to the "GraphiQL" page, where you can explore your custom schema.
+`example.extension.base.graphqls` and `example_extension.extension.graphqls` are files that can be added on top of the existing schema file to "extend" the schema with new functionality. We will approach this in the Advanced section when talking about spliting schemas so that you can make certain modules enable new functionalities as they are enabled.