Resolvers

A resolver performs GraphQL request processing. In general, it is responsible for constructing a query, fetching data and performing any calculations, then transforming the fetched and calculated data into a GraphQL array format. Finally, it returns the results wrapped by a callable function.

A GraphQL request is represented by the following arguments, which will be processed by a resolver:

A GraphQL resolver must implement one of the following interfaces:

• \Magento\Framework\GraphQl\Query\Resolver\BatchResolverInterface

• \Magento\Framework\GraphQl\Query\Resolver\BatchServiceContractResolverInterface

• \Magento\Framework\GraphQl\Query\ResolverInterface

The first two interfaces provide a way to resolve multiple branches/leaves at once (known as batching), while the last one resolves one request at a time. We recommend using batch resolvers for queries because they improve performance by fetching information required to resolve multiple GraphQL requests with a single operation.

Query resolvers

BatchResolverInterface

Batch resolvers gather GraphQL requests for the same field until there is no way to process the tree further without resolving previous requests.

Consider the following example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
query ($filter: ProductAttributeFilterInput!) {
  products (filter: $filter) {
    items {
      id
      sku
      related_products {
        sku
        related_products {
          sku
        }
      }
    }
    total_count
  }
}

The query loads a list of products, the SKUs of their related products, and then any secondary related product SKUs.

Loading a list of related products individually for each product would be expensive performance-wise. With batch resolvers, you can load linked products for all products that were initially found, then group them by root products. After the items branch is resolved, a batch resolver for related_products will be called for the first product found. Instead of resolving the list right away, it will just add the first product to the list of products that require loading additional related products. After all the products from the items branch have been loaded, the lists of related products must be loaded. Then, BatchResolverInterface::resolve() executes with a gathered list of previous requests to related_products branches. At this point, the resolver is able to extract product DTOs from each GraphQL request, load all the product links, sort them by root products, and generate GraphQL values for each branch. After this is done, the same batching will take place when resolving child related_products branches.

The following pseudo-code shows a related_products branch resolver:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
class RelatedProducts implements BatchResolverInterface
{
    ...

    public function resolve(ContextInterface $context, Field $field, array $requests): BatchResponse
    {
        //Get the list of products we need to load related products for
        $rootProductIds = array_map(function ($request) { return $request->getValue()['model']->getId(); }, $requests);

        //Load the links
        $productLinks = $this->service->getRelatedProductLinks($rootProductIds);

        //Sort the links
        $response = new BatchResponse();
        foreach ($requests as $request) {
            $response->addResponse($request, $productLinks[$request->getValue()['model']->getId()]);
        }

        return $response;
    }
}

Each GraphQL request object must be assigned a \Magento\Framework\GraphQl\Query\Resolver\Value result type or any type of data (mixed). This value takes in a callable function to its constructor that will be invoked at the latest possible time for the resolver to acquire its data. As a result, a list of items being resolved can be retrieved all at once by establishing a buffer that contains all relevant parent data to filter and fetch for the children list data.

\Magento\RelatedProductGraphQl\Model\Resolver\Batch\AbstractLinkedProducts contains an example of batch resolver implementation.

BatchServiceContractResolverInterface

Requests for this interface to resolve are gathered into batches in the same way as for BatchResolverInterface, except that the actual resolving is delegated to a batch service contract. The job of the BatchServiceContractResolverInterface resolver is to convert GraphQL requests into DTOs acceptable by the service contract, and then convert results returned by the contract into a GraphQL response.

Consider the same example query:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
query ($filter: ProductAttributeFilterInput!) {
  products (filter: $filter) {
    items {
      id
      sku
      related_products {
        sku
        related_products {
          sku
        }
      }
    }
    total_count
  }
}

Here, we will delegate loading all related products to a service that accepts a list of root product IDs, and then returns individual lists for each.

Pseudo-code for a GraphQL resolver delegating the work to a service contract may look like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
class RelatedProductsResolver implements BatchServiceContractResolverInterface
{
    ...

    public function getServiceContract(): array
    {
        return [ProductLinksRetriever::class, 'getRelatedProducts'];
    }

    public function convertToServiceArgument(ResolveRequestInterface $request)
    {
        return new RootProductCriteria($request->getValue()['model']->getId());
    }

    public function convertFromServiceResult($result, ResolveRequestInterface $request)
    {
        return $result->getLinkedProducts();
    }
}

The getServiceContract() method points to the service contract to be used.

The convertToServiceArgument() method converts GraphQL requests to a criteria item to be passed in a list as the argument to the contract. Remember that batch service contract methods must accept a single argument: a list (array) of criteria objects.

The convertFromServiceResult() method converts one of the result items into a GraphQL response (a \Magento\Framework\GraphQl\Query\Resolver\Value instance or an array). Remember that batch service contracts must return result items in the same order as were the criteria items passed as the method’s list argument.

The batch service contract used in the example would look something like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
class ProductLinksRetriever
{
    ...

    /**
     * @param RootProductCriteria[] $criteriaList
     * @return RelatedProductsFound[]
     */
    public function getRelatedProducts(array $criteriaList): array
    {
        ....
    }
}

class RootProductCriteria
{
    ....

    public function __construct(int $rootProductId)
    {
        $this->productId = $rootProductId;
    }

    public function getRootProductId(): int
    {
        return $this->productId;
    }
}

class RelatedProductsFound
{
    ....

    public function getLinkedProducts(): array
    {
        ....
    }

    public function getRootProductId(): int
    {
        ....
    }
}

A real example can be found at \Magento\CatalogGraphQl\Model\Resolver\Product\BatchProductLinks

ResolverInterface

This interface resolves one branch or leaf at a time. It returns \Magento\Framework\GraphQl\Query\Resolver\Value or any type of data (mixed). This value takes in a callable function to its constructor that will be invoked at the latest possible time for the resolver to acquire its data. As a result, a list of items being resolved can be retrieved all at once by establishing a buffer that contains all relevant parent data to filter and fetch for the children list data.

You can view an example inside the \Magento\BundleGraphQl\Model\Resolver\BundleItemLinks resolver. This resolver takes each bundle option ID and its corresponding parent product ID and stores them in a collection’s filter buffer (in this case, using the \Magento\BundleGraphQl\Model\Resolver\Links\Collection::addIdFilters() function). Each resolver then returns a callable that invokes this collection. The collection caches the result of all link entities it fetched for all the option_id/parent_id combinations. This fetch only needs to occur once for the whole BundleItemLink list, and each resulting callable that is invoked for every link in the list returns an item from the collections cached result.

A Value object wraps a callable object, and you can use \Magento\Framework\GraphQl\Query\Resolver\ValueFactory to create a value.

Mutation requirements

Like queries, mutations are also defined within the <module_name>/etc/schema.graphqls file.

Mutation syntax

1
2
3
type Mutation {
    mutationQueryName(inputParamName: MutationQueryInputType, inputParamName2: MutationQueryInputType2, ...): MutationQueryOutput @resolver(class: "Magento\\<module_name>\\Model\\Resolver\\MutationResolverModel") @doc(description:"Mutation query description")
}

Resolver class

Use the following sample code as a template for the GraphQL resolver mutation class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
<?php
/**
 * Copyright © Magento, Inc. All rights reserved.
 * See COPYING.txt for license details.
 */
declare(strict_types=1);

namespace Magento\<module_name>\Model\Resolver;

use Magento\Framework\GraphQl\Config\Element\Field;
use Magento\Framework\GraphQl\Query\ResolverInterface;
use Magento\Framework\GraphQl\Schema\Type\ResolveInfo;

/**
 * @inheritdoc
 */
class MutationResolverModel implements ResolverInterface
{
    /**
     * @inheritdoc
     */
    public function resolve(Field $field, $context, ResolveInfo $info, array $value = null, array $args = null)
    {
        // resolver functionality ...
    }
}

Example usage

The mutation query below creates an empty cart and returns a cart unique identifier

1
2
3
type Mutation {
    createEmptyCart: String @resolver(class: "\\Magento\\QuoteGraphQl\\Model\\Resolver\\CreateEmptyCart") @doc(description:"Creates an empty shopping cart for a guest or logged in user")
}

Notice that a MutationQueryInput parameter is not specified here and MutationQueryOutput is defined as String type.

The mutation to create a customer’s account is more complex:

1
2
3
type Mutation {
    createCustomer (input: CustomerInput!): CustomerOutput @resolver(class: "\\Magento\\CustomerGraphQl\\Model\\Resolver\\CreateCustomer") @doc(description:"Create customer account")
}

The ! character indicates CustomerInput is a required input parameter. CustomerInput is defined as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
input CustomerInput {
    prefix: String @doc(description: "An honorific, such as Dr., Mr., or Mrs.")
    firstname: String @doc(description: "The customer's first name")
    middlename: String @doc(description: "The customer's middle name")
    lastname: String @doc(description: "The customer's family name")
    suffix: String @doc(description: "A value such as Sr., Jr., or III")
    email: String @doc(description: "The customer's email address. Required")
    date_of_birth: String @doc(description: "The customer's date of birth.")
    taxvat: String @doc(description: "The customer's Tax/VAT number (for corporate customers)")
    gender: Int @doc(description: "The customer's gender(Male - 1, Female - 2)")
    password: String @doc(description: "The customer's password")
    is_subscribed: Boolean @doc(description: "Indicates whether the customer is subscribed to the company's newsletter")
}

In keeping with current security and privacy best practices, be sure you are aware of any potential legal and security risks associated with the storage of customers’ full date of birth (month, day, year) along with other personal identifiers, such as full name, before collecting or processing such data.

The createCustomer mutation returns CustomerOutput object

1
2
3
type CustomerOutput {
    customer: Customer!
}

The customer parameter of the CustomerOutput object is a type of Customer object:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
type Customer @doc(description: "Customer defines the customer name and address and other details") {
    created_at: String @doc(description: "Timestamp indicating when the account was created")
    prefix: String @doc(description: "An honorific, such as Dr., Mr., or Mrs.")
    firstname: String @doc(description: "The customer's first name")
    middlename: String @doc(description: "The customer's middle name")
    lastname: String @doc(description: "The customer's family name")
    suffix: String @doc(description: "A value such as Sr., Jr., or III")
    email: String @doc(description: "The customer's email address. Required")
    default_billing: String @doc(description: "The ID assigned to the billing address")
    default_shipping: String @doc(description: "The ID assigned to the shipping address")
    date_of_birth: String @doc(description: "The customer's date of birth")
    taxvat: String @doc(description: "The customer's Tax/VAT number (for corporate customers)")
    is_subscribed: Boolean @doc(description: "Indicates whether the customer is subscribed to the company's newsletter") @resolver(class: "\\Magento\\CustomerGraphQl\\Model\\Resolver\\IsSubscribed")
    addresses: [CustomerAddress] @doc(description: "An array containing the customer's shipping and billing addresses")
    gender: Int @doc(description: "The customer's gender (Male - 1, Female - 2)")
}

{:.bs-callout-info}
In keeping with current security and privacy best practices, be sure you are aware of any potential legal and security risks associated with the storage of customers’ full date of birth (month, day, year) along with other personal identifiers, such as full name, before collecting or processing such data.

The following example shows the `createCustomer` mutation in action:

```text
mutation {
    createCustomer(
        input: {
            firstname: "John"
            lastname: "Doe"
            email: "j.doe@example.com"
            password: "1w2E3R456"
            is_subscribed: true
        }
    ) {
        customer {
            firstname
            lastname
            email
            is_subscribed
        }
    }
}

A sample response:

1
2
3
4
5
6
7
8
9
10
11
12
{
  "data": {
    "createCustomer": {
      "customer": {
        "firstname": "John",
        "lastname": "Doe",
        "email": "j.doe@example.com",
        "is_subscribed": true
      }
    }
  }
}