...

GraphQL - What is it?

Please read our beginners guide for a quick overview of GraphQL's core concepts: /wiki/spaces/~712020ed0261f15a044ee387ddaa27aaf37f0d/pages/840728681.

Quickstart - Create an Internal Query

Create the schema

• Create a webapi directory in your plugin root

• Under the webapi create a ajax directory

• Create a schema.graphqls file under the ajax directory

• In schema.graphqls let’s define the todo_item type by adding the following:

  • Code Block
    language graphql
    type local_todo_item { id: core_id title: String completed_at: core_date }

  • This adds a new type with id, title and completed_at which we will have access to when using this type.

Create the query

We’ll start off our APIs with creating a query to retrieve a list of the type todo_item.

• In schema.graphqls define the result we’ll get back from the query by defining the following type:

  • Code Block
    language graphql
    type local_todo_items_result { items: [local_todo_item!]! }

  • Notice here we’ve used ! in two places. This indicates the field is non-nullable. We’ve used this here to say that we always expect an array, by putting the exclamation mark on the outside of the array [...]!. We also used to to say that the elements of the array cannot be null [my_type!].

• Now we have the result defined, let’s define the query. We do this by extending the type Query and adding our query into it. Let’s do this:

  • Code Block
    language graphql
    extend type Query { local_todo_items: local_todo_items_result! }

  • This defines that the query local_todo_items should return the local_todo_items_result type we defined earlier

Creating the persisted query

The persisted query is a definition of the query for the frontend component to import. We name this file the query name, minus the component name of the plugin we’re working with.

...

• Create the persisted query file in the webapi/ajax/items.graphql with the following:

  • Code Block
    language graphql
    query local_todo_items { items { id title completed_at } }

Create the backend

Now we need to create the PHP backend to handle the query.

• First we’ll create the directory for the query resolver by creating the following directory /server/local/todo/classes/webapi/resolver/query

• Now let’s create the query resolver class, items.php in the directory we just created.

  • Code Block
    language php
    <?php namespace local_todo\webapi\resolver\query; use core\webapi\execution_context; use core\webapi\query_resolver; use local_todo\entity\item; class items extends query_resolver { /** * @inheritDoc * @throws \coding_exception */ public static function resolve(array $args, execution_context $ec) { global $USER; $items = item::repository() ->where('user_id', $USER->id) ->order_by('id') ->get(); return ['items' => $items]; } }

  • In this file we’ve defined the query resolve and we’re using the ORM of local_todo to return a list of items.

• Now we create the type resolver directory /server/local/todo/classes/webapi/resolver/type/ and the type resolver for item item.php in the directory.

  • Code Block
    language php
    <?php namespace local_todo\webapi\resolver\type; use core\webapi\execution_context; use core\webapi\type_resolver; class item extends type_resolver { /** * @param string $field - The field being requested * @param $source - In the case, source will be our `item` entity class as it's what's returned from the query resolver * @param array $args * @param execution_context $ec * @return mixed|void */ public static function resolve(string $field, $source, array $args, execution_context $ec) { return $source->$field; } }

Testing Queries

Testing Mutations

TODO:

• Screenshots of how to set up the dev_graphql_executor

  • Maybe update the main doc for this

• Add how to test generally - the below is not enough, need proper guidance

• Tidy up steps - they can be much cleaner

• 👋 Say hello to whoever made it this far and is now just nosey 😂

...