HOME

Mini Shell 1.0
DIR:/home/austenwhite.co.uk/www/dev/vendor/webonyx/graphql-php/docs/
Current File : //home/austenwhite.co.uk/www/dev/vendor/webonyx/graphql-php/docs/schema-definition.md
# Schema Definition

The schema is a container of your type hierarchy, which accepts root types in a constructor and provides
methods for receiving information about your types to internal GraphQL tools.

In **graphql-php**, the schema is an instance of [`GraphQL\Type\Schema`](class-reference.md#graphqltypeschema):

```php
use GraphQL\Type\Schema;

$schema = new Schema([
    'query' => $queryType,
    'mutation' => $mutationType,
]);
```

See possible constructor options [below](#configuration-options).

## Query and Mutation types

The schema consists of two root types:

- **Query** type is a surface of your read API
- **Mutation** type (optional) exposes write API by declaring all possible mutations in your app.

Query and Mutation types are regular [object types](type-definitions/object-types.md) containing root-level fields
of your API:

```php
use GraphQL\Type\Definition\ObjectType;
use GraphQL\Type\Definition\Type;

$queryType = new ObjectType([
    'name' => 'Query',
    'fields' => [
        'hello' => [
            'type' => Type::string(),
            'resolve' => fn () => 'Hello World!',
        ],
        'hero' => [
            'type' => $characterInterface,
            'args' => [
                'episode' => [
                    'type' => $episodeEnum,
                ],
            ],
            'resolve' => fn ($rootValue, array $args): Hero => StarWarsData::getHero($args['episode'] ?? null),
        ]
    ]
]);

$mutationType = new ObjectType([
    'name' => 'Mutation',
    'fields' => [
        'createReview' => [
            'type' => $createReviewOutput,
            'args' => [
                'episode' => Type::nonNull($episodeEnum),
                'review' => Type::nonNull($reviewInputObject),
            ],
            // TODO
            'resolve' => fn ($rootValue, array $args): Review => StarWarsData::createReview($args['episode'], $args['review']),
        ]
    ]
]);
```

Keep in mind that other than the special meaning of declaring a surface area of your API,
those types are the same as any other [object type](type-definitions/object-types.md), and their fields work
exactly the same way.

**Mutation** type is also just a regular object type. The difference is in semantics.
Field names of Mutation type are usually verbs and they almost always have arguments - quite often
with complex input values (see [Mutations and Input Types](type-definitions/inputs.md) for details).

## Configuration Options

The schema constructor expects an instance of [`GraphQL\Type\SchemaConfig`](class-reference.md#graphqltypeschemaconfig)
or an array with the following options:

| Option       | Type                                                | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| query        | `ObjectType` or `callable(): ?ObjectType` or `null` | **Required.** Object type (usually named `Query`) containing root-level fields of your read API                                                                                                                                                                                                                                                                                                                                                               |
| mutation     | `ObjectType` or `callable(): ?ObjectType` or `null` | Object type (usually named `Mutation`) containing root-level fields of your write API                                                                                                                                                                                                                                                                                                                                                                         |
| subscription | `ObjectType` or `callable(): ?ObjectType` or `null` | Reserved for future subscriptions implementation. Currently presented for compatibility with introspection query of **graphql-js**, used by various clients (like Relay or GraphiQL)                                                                                                                                                                                                                                                                          |
| directives   | `array<Directive>`                                  | A full list of [directives](type-definitions/directives.md) supported by your schema. By default, contains built-in **@skip** and **@include** directives.<br><br> If you pass your own directives and still want to use built-in directives - add them explicitly. For example:<br><br> _array_merge(GraphQL::getStandardDirectives(), [$myCustomDirective]);_                                                                                               |
| types        | `array<ObjectType>`                                 | List of object types which cannot be detected by **graphql-php** during static schema analysis.<br><br>Most often this happens when the object type is never referenced in fields directly but is still a part of a schema because it implements an interface which resolves to this object type in its **resolveType** callable. <br><br> Note that you are not required to pass all of your types here - it is simply a workaround for a concrete use-case. |
| typeLoader   | `callable(string $name): Type`                      | Expected to return a type instance given the name. Must always return the same instance if called multiple times, see [lazy loading](#lazy-loading-of-types). See section below on lazy type loading.                                                                                                                                                                                                                                                         |

### Using config class

If you prefer a fluid interface for the config with auto-completion in IDE and static time validation,
use [`GraphQL\Type\SchemaConfig`](class-reference.md#graphqltypeschemaconfig) instead of an array:

```php
use GraphQL\Type\SchemaConfig;
use GraphQL\Type\Schema;

$config = SchemaConfig::create()
    ->setQuery($myQueryType)
    ->setTypeLoader($myTypeLoader);

$schema = new Schema($config);
```

## Lazy loading of types

If your schema makes use of a large number of complex or dynamically-generated types, they can become a performance concern.
There are a few best practices that can lessen their impact:

1. Use a type registry.
   This will put you in a position to implement your own caching and lookup strategies, and GraphQL won't need to preload a map of all known types to do its work.

2. Define each custom type as a callable that returns a type, rather than an object instance.
   Then, the work of instantiating them will only happen as they are needed by each query.

3. Define all of your object **fields** as callbacks.
   If you're already doing #2 then this isn't needed, but it's a quick and easy precaution.

It is recommended to centralize this kind of functionality in a type registry.
A typical example might look like the following:

```php
// StoryType.php
use GraphQL\Type\Definition\ObjectType;

final class StoryType extends ObjectType
{
    public function __construct()
    {
        parent::__construct([
            'fields' => static fn (): array => [
                'author' => [
                    'type' => Types::author(),
                    'resolve' => static fn (Story $story): ?Author => DataSource::findUser($story->authorId),
                ],
            ],
        ]);
    }
}

// AuthorType.php
use GraphQL\Type\Definition\ObjectType;

final class AuthorType extends ObjectType
{
    public function __construct()
    {
        parent::__construct([
            'description' => 'Writer of books',
            'fields' => static fn (): array => [
                'firstName' => Types::string(),
            ],
        ]);
    }
}

// Types.php
use GraphQL\Type\Definition\Type;
use GraphQL\Type\Definition\NamedType;

final class Types
{
    /** @var array<string, Type&NamedType> */
    private static array $types = [];

    /** @return Type&NamedType */
    public static function load(string $typeName): Type
    {
        if (isset(self::$types[$typeName])) {
            return self::$types[$typeName];
        }

        // For every type, this class must define a method with the same name
        // but the first letter is in lower case.
        $methodName = match ($typeName) {
            'ID' => 'id',
            default => lcfirst($typeName),
        };
        if (! method_exists(self::class, $methodName)) {
            throw new \Exception("Unknown GraphQL type: {$typeName}.");
        }

        $type = self::{$methodName}(); // @phpstan-ignore-line variable static method call
        if (is_callable($type)) {
            $type = $type();
        }

        return self::$types[$typeName] = $type;
    }

    /** @return Type&NamedType */
    private static function byClassName(string $className): Type
    {
        $classNameParts = explode('\\', $className);
        $baseClassName = end($classNameParts);
        // All type classes must use the suffix Type.
        // This prevents name collisions between types and PHP keywords.
        $typeName = preg_replace('~Type$~', '', $baseClassName);

        // Type loading is very similar to PHP class loading, but keep in mind
        // that the **typeLoader** must always return the same instance of a type.
        // We can enforce that in our type registry by caching known types.
        return self::$types[$typeName] ??= new $className;
    }

    /** @return \Closure(): (Type&NamedType) */
    private static function lazyByClassName(string $className): \Closure
    {
        return static fn () => self::byClassName($className);
    }

    public static function boolean(): ScalarType { return Type::boolean(); }
    public static function float(): ScalarType { return Type::float(); }
    public static function id(): ScalarType { return Type::id(); }
    public static function int(): ScalarType { return Type::int(); }
    public static function string(): ScalarType { return Type::string(); }
    public static function author(): callable { return self::lazyByClassName(AuthorType::class); }
    public static function story(): callable { return self::lazyByClassName(StoryType::class); }
    ...
}

// api/index.php
use GraphQL\Type\Definition\ObjectType;

$schema = new Schema([
    'query' => new ObjectType([
        'name' => 'Query',
        'fields' => static fn() => [
            'story' => [
                'args'=>[
                  'id' => Types::int(),
                ],
                'type' => Types::story(),
                'description' => 'Returns my A',
                'resolve' => static fn ($rootValue, array $args): ?Story => DataSource::findStory($args['id']),
            ],
        ],
    ]),
    'typeLoader' => Types::load(...),
]);
```

A working demonstration of this kind of architecture can be found in the [01-blog](https://github.com/webonyx/graphql-php/blob/master/examples/01-blog) sample.

## Schema Validation

By default, the schema is created with only shallow validation of type and field definitions  
(because validation requires a full schema scan and is very costly on bigger schemas).

There is a special method **assertValid()** on the schema instance which throws
`GraphQL\Error\InvariantViolation` exception when it encounters any error, like:

- Invalid types used for fields/arguments
- Missing interface implementations
- Invalid interface implementations
- Other schema errors...

Schema validation is supposed to be used in CLI commands or during a build step of your app.
Don't call it in web requests in production.

Usage example:

```php
try {
    $schema = new GraphQL\Type\Schema([
        'query' => $myQueryType
    ]);
    $schema->assertValid();
} catch (GraphQL\Error\InvariantViolation $e) {
    echo $e->getMessage();
}
```