Laravel GraphQL

https://github.com/rebing/graphql-laravel
Admin
This package provides an integration of GraphQL for Laravel, allowing for the creation of queries...
Tokens:130,058
Snippets:920
Trust Score:8.2
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### authorize method example

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/field.md

Example implementation of authorize that returns true if a user is present in the context.

```php
public function authorize($root, array $args, $ctx, ?ResolveInfo $resolveInfo = null): bool
{
    return (bool) ($ctx->user ?? null);
}
```

--------------------------------

### Install OpenTelemetry API package

Source: https://github.com/rebing/graphql-laravel/blob/master/README.md

Required before enabling the OpenTelemetry tracing driver. Installs the open-telemetry/api package version ^1.0.

```bash
composer require open-telemetry/api
```

--------------------------------

### UpdateUserMutation example with cross-field rules

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/validation.md

Example mutation showing top-level args where no prefixing occurs because email/password are siblings at the same level. For nested inputs, rules are auto-prefixed to paths like recipients.0.createParams.

```php
class UpdateUserMutation extends Mutation
{
    public function args(): array
    {
        return [
            'id' => ['type' => Type::nonNull(Type::id())],
            'email' => ['type' => Type::string()],
            'password' => ['type' => Type::string()],
            'name' => ['type' => Type::string()],
        ];
    }

    public function rules(array $args = []): array
    {
        return [
            'password' => 'required_with:email', // "email" is a sibling at the same level
            'email' => 'prohibits:password',
        ];
    }
}
```

--------------------------------

### Example: CreatePostMutation with alias for author_id

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/validation.md

Shows how to define an alias in args() so the client sends 'authorId' and the resolver receives $args['author_id'].

```php
class CreatePostMutation extends Mutation
{
    public function args(): array
    {
        return [
            'title' => ['type' => Type::string()],
            'author_id' => [
                'type' => Type::int(),
                'alias' => 'authorId', // client sends "authorId"
            ],
        ];
    }

    public function resolve($root, array $args)
    {
        // $args['author_id'] is now populated from the "authorId" request key
    }
}
```

--------------------------------

### Resolver middleware class example (ResolvePage)

Source: https://github.com/rebing/graphql-laravel/blob/master/README.md

Example middleware that sets the Paginator current page from the 'pagination' argument. Extends Rebing\GraphQL\Support\Middleware and uses the handle method with ResolveInfo and Closure.

```php
declare(strict_types = 1);
namespace App\GraphQL\Middleware;

use Closure;
use GraphQL\Type\Definition\ResolveInfo;
use Illuminate\Pagination\Paginator;
use Rebing\GraphQL\Support\Middleware;

class ResolvePage extends Middleware
{
    public function handle($root, array $args, $context, ResolveInfo $info, Closure $next)
    {
        Paginator::currentPageResolver(function () use ($args) {
            return $args['pagination']['page'] ?? 1;
        });

        return $next($root, $args, $context, $info);
    }
}
```

--------------------------------

### Install dependencies with Composer

Source: https://github.com/rebing/graphql-laravel/blob/master/CONTRIBUTING.md

Run these commands after cloning the repository to install the main dependencies. Requires PHP 8.2+ with pdo_sqlite and Composer.

```bash
cd /path/to/graphql-laravel
composer install
```

--------------------------------

### Example: registering a parameter injector

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/field.md

Shows how to implement ResolverParameterInjector and register it with Field::registerParameterInjector(). Injectors are consulted in registration order; the first supports() wins.

```php
use Rebing\GraphQL\Support\Contracts\ResolverParameterInjector;
use Rebing\GraphQL\Support\Field;

class SelectFieldsInjector implements ResolverParameterInjector
{
    public function supports(string $className): bool
    {
        return $className === \Rebing\GraphQL\SelectFields::class;
    }

    public function resolve(string $className, array $arguments, array $fieldsAndArguments, Field $field): mixed
    {
        return new \Rebing\GraphQL\SelectFields($arguments[3], ...);
    }
}

Field::registerParameterInjector(new SelectFieldsInjector);
```

--------------------------------

### Install package via Composer

Source: https://github.com/rebing/graphql-laravel/blob/master/README.md

Run this command to require the rebing/graphql-laravel package in your Laravel project.

```bash
composer require rebing/graphql-laravel
```

--------------------------------

### Example UserSchema class implementing ConfigConvertible

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/contracts.md

Shows a complete class-based schema. Use the make:graphql:schemaConfig generator for the skeleton.

```php
namespace App\GraphQL\Schemas;

use App\GraphQL\Mutations\CreatePostMutation;
use App\GraphQL\Queries\PostsQuery;
use App\GraphQL\Types\PostType;
use Rebing\GraphQL\Support\Contracts\ConfigConvertible;

class UserSchema implements ConfigConvertible
{
    public function toConfig(): array
    {
        return [
            'query' => [PostsQuery::class],
            'mutation' => [CreatePostMutation::class],
            'types' => [PostType::class],
            'middleware' => ['auth:api'],
            'method' => ['POST', 'GET'],
        ];
    }
}
```

--------------------------------

### SchemaConfig stub output

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/console-commands.md

Generated example of a schema configuration class implementing ConfigConvertible. Includes placeholder arrays for query, mutation, and types.

```php
<?php

declare(strict_types=1);

namespace App\GraphQL\Schemas;

use Rebing\GraphQL\Support\Contracts\ConfigConvertible;

class UserSchema implements ConfigConvertible
{
    public function toConfig(): array
    {
        return [
            'query' => [
                // ExampleQuery::class,
            ],

            'mutation' => [
                // ExampleMutation::class,
            ],

            'types' => [
                // ExampleType::class,
            ],
        ];
    }
}
```

--------------------------------

### Configuring execution middleware in config/graphql.php

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/execution-middleware.md

Configuration example showing how to register execution middleware in the config file. The list includes default middleware and the custom TimingExecutionMiddleware.

```php
// config/graphql.php
'execution_middleware' => [
    \Rebing\GraphQL\Support\ExecutionMiddleware\ValidateOperationParamsMiddleware::class,
    \Rebing\GraphQL\Support\ExecutionMiddleware\AutomaticPersistedQueriesMiddleware::class,
    \Rebing\GraphQL\Support\ExecutionMiddleware\AddAuthUserContextValueMiddleware::class,
    \App\GraphQL\Middleware\Execution\TimingExecutionMiddleware::class,
],
```

--------------------------------

### Full example: Query with authorization, validation, and custom messages

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/field.md

Complete example of a GraphQL query using Rebing\GraphQL\Support\Query. Includes authorization via `authorize` and `getAuthorizationMessage`, validation rules and custom error messages, and a resolver that fetches a user by ID.

```php
namespace App\GraphQL\Queries;

use GraphQL\Type\Definition\ResolveInfo;
use GraphQL\Type\Definition\Type;
use Rebing\GraphQL\Support\Facades\GraphQL;
use Rebing\GraphQL\Support\Query;

class UserQuery extends Query
{
    protected $attributes = ['name' => 'user'];

    public function type(): Type
    {
        return GraphQL::type('user');
    }

    public function args(): array
    {
        return [
            'id' => ['name' => 'id', 'type' => Type::nonNull(Type::int())],
            'email' => ['name' => 'email', 'type' => Type::string()],
        ];
    }

    public function rules(array $args = []): array
    {
        return ['id' => 'required_without:email'];
    }

    public function validationErrorMessages(array $args = []): array
    {
        return ['id.required_without' => 'Provide an id or an email.'];
    }

    public function authorize($root, array $args, $ctx, ?ResolveInfo $resolveInfo = null): bool
    {
        return null !== ($ctx->user ?? null);
    }

    public function getAuthorizationMessage(): string
    {
        return 'You must be logged in to query users.';
    }

    public function resolve($root, array $args, $ctx, ResolveInfo $resolveInfo)
    {
        return \App\Models\User::where('id', $args['id'])->first();
    }
}
```

--------------------------------

### Logging middleware example

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/middleware.md

Example middleware that logs field resolution time and termination. Includes terminate() method.

```php
namespace App\GraphQL\Middleware;

use Closure;
use GraphQL\Type\Definition\ResolveInfo;
use Illuminate\Support\Facades\Log;
use Rebing\GraphQL\Support\Middleware;

class LogMiddleware extends Middleware
{
    public function handle(mixed $root, array $args, mixed $context, ResolveInfo $info, Closure $next): mixed
    {
        $start = microtime(true);

        $result = $next($root, $args, $context, $info);

        Log::debug('resolved field', [
            'field' => $info->fieldName,
            'ms' => (microtime(true) - $start) * 1000,
        ]);

        return $result;
    }

    public function terminate($field, $root, $args, $context, $result): void
    {
        Log::debug('terminating after response', ['field' => $field->name]);
    }
}

```

```php
// In the Query class
class UsersQuery extends Query
{
    protected $middleware = [LogMiddleware::class];

    // ...
}

```

--------------------------------

### Example: execute a raw operation

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/graphql.md

Shows how to build an OperationParams from a base OperationParams and call execute. The result is a decorated array with 'data' and 'errors' keys.

```php
use GraphQL\Server\OperationParams as BaseOperationParams;
use Rebing\GraphQL\Support\OperationParams;
use Rebing\GraphQL\Support\Facades\GraphQL;

$base = new BaseOperationParams;
$base->query = '{ examples { name } }';
$base->variables = [];
$base->operation = null;

$params = new OperationParams($base);

$result = GraphQL::execute('default', $params); // -> ['data' => ..., 'errors' => ...]
```

--------------------------------

### Example: Registering global resolver middleware

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/graphql.md

Shows how to prepend and append global resolver middleware using the GraphQL facade. Prepended middleware runs before per-field middleware, while appended middleware runs after.

```php
use Rebing\GraphQL\Support\Facades\GraphQL;

GraphQL::prependGlobalResolverMiddleware(\App\GraphQL\Middleware\TraceMiddleware::class);
GraphQL::appendGlobalResolverMiddleware(\App\GraphQL\Middleware\LogMiddleware::class);
```

--------------------------------

### AliasArguments constructor and get() method signature

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/validation.md

Constructor computes maxDepth from request arguments. get() returns request arguments with aliased keys renamed.

```php
public function __construct(array $queryArguments, array $requestArguments)
{
    // computes maxDepth from the request arguments
}

/** @return array<string, mixed> */
public function get(): array
```

--------------------------------

### CreateUserInput example extending InputType

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/type.md

Example of a custom input type. Defines fields with validation rules and an alias for argument mapping. The 'isOneOf' attribute is set to false.

```php
namespace App\GraphQL\Inputs;

use GraphQL\Type\Definition\Type;
use Rebing\GraphQL\Support\InputType;

class CreateUserInput extends InputType
{
    protected $attributes = [
        'name' => 'CreateUserInput',
        'description' => 'Input for creating a user',
        'isOneOf' => false,
    ];

    public function fields(): array
    {
        return [
            'name' => ['type' => Type::nonNull(Type::string()), 'rules' => ['min:3']],
            'email' => [
                'type' => Type::nonNull(Type::string()),
                'rules' => ['required', 'email'],
                'alias' => 'email_address', // maps request key 'email_address' -> 'email'
            ],
        ];
    }
}
```

--------------------------------

### Example of implementing InterfaceType

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/type.md

Example implementation of InterfaceType for a Content interface. Defines fields id and title, and resolveType returns the appropriate object type based on the root instance.

```php
namespace App\GraphQL\Interfaces;

use GraphQL\Type\Definition\Type;
use Rebing\GraphQL\Support\InterfaceType;

class ContentInterface extends InterfaceType
{
    protected $attributes = ['name' => 'Content'];

    public function fields(): array
    {
        return [
            'id' => ['type' => Type::nonNull(Type::id())],
            'title' => ['type' => Type::string()],
        ];
    }

    public function resolveType($root)
    {
        // return one of the implementing ObjectTypes
        return $root instanceof \App\Models\Post
            ? \Rebing\GraphQL\Support\Facades\GraphQL::type('post')
            : \Rebing\GraphQL\Support\Facades\GraphQL::type('video');
    }
}
```

--------------------------------

### CsrfGuard::using() usage examples

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/csrf-guard.md

Three usage examples from the source docblock: strict default, permissive mode, and custom header name. Each shows how to configure the middleware for different client scenarios.

```php
// Strict (default) -- suitable for session-authenticated browser SPAs:
CsrfGuard::using()

// Permissive -- allows non-browser clients that don't send Sec-Fetch-Site
// or custom headers (mobile apps, legacy integrations):
CsrfGuard::using(strictWhenAmbiguous: false)

// Custom header name (Apollo ecosystem convention):
CsrfGuard::using(customHeaderName: 'Apollo-Require-Preflight')
```

--------------------------------

### Custom execution middleware example

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/execution-middleware.md

Example of a custom execution middleware that measures execution time and adds it to the result extensions. It calls $next() to continue the pipeline and appends timing data to the 'timing' extension if it exists.

```php
namespace App\GraphQL\Middleware\Execution;

use Closure;
use GraphQL\Executor\ExecutionResult;
use GraphQL\Type\Schema;
use Rebing\GraphQL\Support\ExecutionMiddleware\AbstractExecutionMiddleware;
use Rebing\GraphQL\Support\OperationParams;

class TimingExecutionMiddleware extends AbstractExecutionMiddleware
{
    public function handle(string $schemaName, Schema $schema, OperationParams $params, $rootValue, $contextValue, Closure $next): ExecutionResult
    {
        $start = microtime(true);

        $result = $next($schemaName, $schema, $params, $rootValue, $contextValue);

        if (isset($result->extensions['timing'])) {
            $result->extensions['timing'] = $result->extensions['timing'] ?? [];
            $result->extensions['timing'][] = ['total_ms' => (microtime(true) - $start) * 1000];
        }

        return $result;
    }
}
```

--------------------------------

### Manual provider usage in config/app.php

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/service-provider.md

Example of manually registering the service provider and alias in a standalone Laravel app's config/app.php.

```php
// config/app.php providers
'providers' => [
    Rebing\GraphQL\GraphQLServiceProvider::class,
],
// aliases
'aliases' => [
    'GraphQL' => Rebing\GraphQL\Support\Facades\GraphQL::class,
],
```

--------------------------------

### GraphQL query to fetch users

Source: https://github.com/rebing/graphql-laravel/blob/master/README.md

Example GraphQL query to fetch users with id and email fields. Send this as the 'query' input in a POST request to the /graphql endpoint.

```graphql
query FetchUsers {
    users {
        id
        email
    }
}
```

--------------------------------

### Input stub (with --oneof note)

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/console-commands.md

Generated example of an input type class extending InputType. Includes attributes with isOneOf set to false and a fields method with a test field.

```php
<?php

declare(strict_types=1);

namespace App\GraphQL\Inputs;

use GraphQL\Type\Definition\Type;
use Rebing\GraphQL\Support\InputType;

class CreateUserInput extends InputType
{
    protected $attributes = [
        'name' => 'CreateUserInput',
        'description' => 'An example input',
        'isOneOf' => false,
    ];

    public function fields(): array
    {
        return [
            'test' => [
                'type' => Type::string(),
                'description' => 'A test field',
            ],
        ];
    }
}
```

--------------------------------

### Example resolve method in a GraphQL query

Source: https://github.com/rebing/graphql-laravel/blob/master/README.md

Shows a query class with a resolve method that receives the hard-coded parameters ($root, $args, $context) and injected dependencies like ResolveInfo and a custom logging class. The method logs a message and returns all users.

```php
declare(strict_types = 1);
namespace App\GraphQL\Queries;

use App\Models\User;
use Rebing\GraphQL\Support\Facades\GraphQL;
use GraphQL\Type\Definition\Type;
use GraphQL\Type\Definition\ResolveInfo;
use Rebing\GraphQL\Support\Query;
use SomeClassNamespace\SomeClassThatDoLogging;

class UsersQuery extends Query
{
    protected $attributes = [
        'name' => 'users',
    ];

    public function type(): Type
    {
        return Type::listOf(GraphQL::type('User'));
    }

    public function args(): array
    {
        return [
            'id' => [
                'type' => Type::string(),
            ]
        ];
    }

    public function resolve($root, array $args, $context, ResolveInfo $info, SomeClassThatDoLogging $logging)
    {
        $logging->log('fetched user');

        $users = User::all();

        return $users->get();
    }
}
```

--------------------------------

### Helpers::applyEach usage example

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/controller.md

Shows how to use applyEach with an array and a single value. The callback is applied to each element, returning an array or a single result.

```php
use Rebing\GraphQL\Helpers;

$result = Helpers::applyEach(
    fn (string $op) => strtoupper($op),
    ['a', 'b'],
); // ['A', 'B']

$single = Helpers::applyEach(
    fn (string $op) => strtoupper($op),
    'a',
); // 'A'
```

--------------------------------

### Wrap Types Example in Query

Source: https://github.com/rebing/graphql-laravel/blob/master/README.md

Shows how to wrap a type to add extra information to queries and mutations, similar to pagination. The resolve method returns an array with 'data' and 'messages' keys.

```php
public function type(): Type
{
    return GraphQL::wrapType(
        'PostType',
        'PostMessageType',
        \App\GraphQL\Types\WrapMessagesType::class,
    );
}

public function resolve($root, array $args)
{
    return [
        'data' => Post::find($args['post_id']),
        'messages' => new Collection([
                new SimpleMessage("Congratulations, the post was found"),
                new SimpleMessage("This post cannot be edited", "warning"),
        ]),
    ];
}
```

--------------------------------

### Type registration example

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/graphql.md

Shows how to register types with `GraphQL::addType` and `GraphQL::addTypes`, clear a type, and retrieve all registered types. Demonstrates custom name keying and name inference from attributes when no name is provided.

```php
GraphQL::addType(\App\GraphQL\Types\UserType::class, 'user');
GraphQL::addTypes(['user' => \App\GraphQL\Types\UserType::class]);

GraphQL::clearType('user');
$allRegistered = GraphQL::getTypes();

// With a custom name keying:
GraphQL::addType(\App\GraphQL\Types\UserType::class); // infers 'user' from attributes
```

--------------------------------

### OpenTelemetryTracingDriver startOperation method

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/tracing.md

Starts an operation span with SpanKind::KIND_SERVER. Span name is the operation type (query/mutation/subscription) or 'GraphQL Operation' when unknown. Sets attributes for schema name, operation name/type, and document (when include_document is enabled). Returns a new OpenTelemetryContext after activating the span.

```php
public function startOperation(string $schemaName, ?string $operationName, ?string $operationType, ?string $source): mixed
```

--------------------------------

### Basic schema usage with facade

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/graphql.md

Example of retrieving the default and named schemas using the GraphQL facade. The default schema is used when no name is provided.

```php
use Rebing\GraphQL\Support\Facades\GraphQL;

$schema = GraphQL::schema();            // default schema
$schema = GraphQL::schema('user');      // named schema
```

--------------------------------

### Implement ConfigConvertible for schema class

Source: https://github.com/rebing/graphql-laravel/blob/master/README.md

Example of a schema configuration class implementing ConfigConvertible. The toConfig method returns the schema configuration array. Use 'php artisan make:graphql:schemaConfig' to generate such a class automatically.

```php
declare(strict_types = 1);
namespace App\GraphQL\Schemas;

use Rebing\GraphQL\Support\Contracts\ConfigConvertible;

class DefaultSchema implements ConfigConvertible
{
    public function toConfig(): array
    {
        return [
            'query' => [
                ExampleQuery::class,
            ],
            'mutation' => [
                ExampleMutation::class,
            ],
            'types' => [
            
            ],
        ];
    }
}
```

--------------------------------

### Example: manual construction and execution

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/operation-params.md

Shows how to manually create an OperationParams instance from a BaseOperationParams and use it to execute a GraphQL query. Demonstrates getOriginalInput(), isReadOnly(), getParsedQuery(), and GraphQL::execute().

```php
use GraphQL\Server\OperationParams as BaseOperationParams;
use Rebing\GraphQL\Support\OperationParams;
use Rebing\GraphQL\Support\Facades\GraphQL;

$base = BaseOperationParams::create([
    'query' => 'query ($id: ID!) { user(id: $id) { name } }',
    'variables' => ['id' => 42],
    'operationName' => null,
]);

$params = new OperationParams($base);

echo $params->getOriginalInput('query');      // raw query string
$params->isReadOnly();                        // false

$document = $params->getParsedQuery();         // DocumentNode (parsed once)

$result = GraphQL::execute('default', $params);
```

--------------------------------

### RulesInFields get() method signature

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/validation.md

Returns collected rules keyed by dot-notation path. Walks the selection tree and reads each field's config args.

```php
/** @return array<string,mixed> */
public function get(): array
```

--------------------------------

### Example implementation of ResolverParameterInjector

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/contracts.md

Implements the interface to inject the current authenticated user. `supports()` returns true only for `\App\Models\User`. `resolve()` extracts the context from `$arguments[2]` and returns `$context->user` or null.

```php
use GraphQL\Type\Definition\ResolveInfo;
use Rebing\GraphQL\Support\Contracts\ResolverParameterInjector;
use Rebing\GraphQL\Support\Field;

class CurrentUserInjector implements ResolverParameterInjector
{
    public function supports(string $className): bool
    {
        return \App\Models\User::class === $className;
    }

    public function resolve(string $className, array $arguments, array $fieldsAndArguments, Field $field): mixed
    {
        $context = $arguments[2]; // [root, args, ctx, info]

        return $context->user ?? null;
    }
}
```

--------------------------------

### Testing a non-default schema by URL path

Source: https://github.com/rebing/graphql-laravel/blob/master/README.md

Pass the schema name as part of the URL path to test a non-default schema. This example expects an unauthorized response for the /graphql/user endpoint.

```php
public function test_user_schema_requires_auth(): void
{
    $response = $this->postJson('/graphql/user', [
        'query' => '{ profile { id email } }',
    ]);

    $response->assertUnauthorized();
}
```

--------------------------------

### TracingExecutionMiddleware constructor and handle method signature

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/tracing.md

Defines the middleware that manages tracing for GraphQL operations. The constructor injects a TracingManager, and the handle method wraps the context in a TracingOperationScope when field tracing is enabled, starts an operation trace, and ends it on success or failure.

```php
public function __construct(
    private readonly TracingManager $tracingManager,
)

public function handle(
    string $schemaName,
    Schema $schema,
    OperationParams $params,
    $rootValue,
    $contextValue,
    Closure $next,
): ExecutionResult
```

--------------------------------

### Testing mutations with postJson

Source: https://github.com/rebing/graphql-laravel/blob/master/README.md

Send a GraphQL mutation to update a user's password and assert the response. This example verifies the mutation returns the expected ID.

```php
public function test_can_update_user_password(): void
{
    $response = $this->postJson('/graphql', [
        'query' => 'mutation { updateUserPassword(id: "1", password: "newpassword") { id } }',
    ]);

    $response->assertOk()
        ->assertJsonPath('data.updateUserPassword.id', '1');
}
```

--------------------------------

### Basic GraphQL query example

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/graphql.md

Basic usage of GraphQL::query with variables and options. Uses the default schema and operation name. Returns a plain array with the execution result.

```php
use Rebing\GraphQL\Support\Facades\GraphQL;

$result = GraphQL::query(
    'query UserQuery($id: ID!) { user(id: $id) { name email } }',
    ['id' => 1],
    ['schema' => 'default', 'operationName' => 'UserQuery'],
);
```

--------------------------------

### Custom GraphQL controller implementation

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/controller.md

Example of a custom controller that overrides the default query action. It can include custom logic or response decorators before delegating.

```php
namespace App\Http\Controllers;

use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Rebing\GraphQL\GraphQL;

class MyGraphQLController extends \Illuminate\Routing\Controller
{
    public function query(Request $request, GraphQL $graphql): JsonResponse
    {
        // custom logic or response decorators before delegating
        return response()->json(['custom' => true]);
    }
}
```

--------------------------------

### Apollo Client APQ setup (apollo.js)

Source: https://github.com/rebing/graphql-laravel/blob/master/README.md

Client-side integration for Automatic Persisted Queries (APQ) using Apollo Client and Vue 3. The createPersistedQueryLink automatically manages the APQ flow, sending a hash instead of the full query to reduce bandwidth.

```javascript
// [example apollo.js]

import { ApolloClient, InMemoryCache, HttpLink, ApolloLink } from '@apollo/client/core';
import { createPersistedQueryLink } from '@apollo/client/link/persisted-queries';
import { sha256 } from 'crypto-hash';

const httpLink = new HttpLink({ uri: '/graphql' });
const persistedQueryLink = createPersistedQueryLink({ sha256 });

export const apolloClient = new ApolloClient({
  link: ApolloLink.from([persistedQueryLink, httpLink]),
  cache: new InMemoryCache(),
  connectToDevTools: true,
});
```

--------------------------------

### Querying an endpoint with postJson

Source: https://github.com/rebing/graphql-laravel/blob/master/README.md

Use Laravel's postJson helper to send a GraphQL query to the /graphql endpoint and assert the response structure. This example checks that the response is OK and contains the expected fields for books.

```php
namespace Tests\Feature;

use Tests\TestCase;

class BooksQueryTest extends TestCase
{
    public function test_can_query_books(): void
    {
        $response = $this->postJson('/graphql', [
            'query' => '{ books { id title author } }',
        ]);

        $response->assertOk()
            ->assertJsonStructure([
                'data' => [
                    'books' => [
                        '*' => ['id', 'title', 'author'],
                    ],
                ],
            ]);
    }
}
```

--------------------------------

### Custom LogTracingDriver implementation

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/tracing.md

Example custom driver that logs operation start/end and field resolve events. Implements TracingDriver and uses Laravel's Log facade.

```php
namespace App\GraphQL\Tracing;

use GraphQL\Executor\ExecutionResult;
use GraphQL\Type\Definition\ResolveInfo;
use Illuminate\Support\Facades\Log;
use Rebing\GraphQL\Support\Tracing\TracingDriver;

class LogTracingDriver implements TracingDriver
{
    private float $start;

    public function startOperation(string $schemaName, ?string $operationName, ?string $operationType, ?string $source): mixed
    {
        $this->start = microtime(true);

        Log::debug('graphql operation start', compact('schemaName', 'operationName', 'operationType'));

        return null;
    }

    public function endOperation(mixed $context, ExecutionResult $result): ExecutionResult
    {
        Log::debug('graphql operation end', ['duration_ms' => (microtime(true) - $this->start) * 1000]);

        return $result;
    }

    public function startFieldResolve(ResolveInfo $info): mixed
    {
        return null;
    }

    public function endFieldResolve(mixed $context, ResolveInfo $info): void
    {
        // no-op
    }
}
```

--------------------------------

### Install SelectFields external package

Source: https://github.com/rebing/graphql-laravel/blob/master/UPGRADE.md

Required for applications using SelectFields after it was extracted to a separate package. The package's service provider auto-registers, and all classes remain at their original namespaces, so no import changes are needed.

```bash
composer require rebing/graphql-laravel-select-fields
```

--------------------------------

### Example: Using GraphQL::paginate in a query

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/graphql.md

Shows a complete query class that returns a paginated type for the 'user' type. Requires importing the GraphQL facade and extending Rebing\GraphQL\Support\Query.

```php
use Rebing\GraphQL\Support\Facades\GraphQL;

class UsersQuery extends \Rebing\GraphQL\Support\Query
{
    public function type(): \GraphQL\Type\Definition\Type
    {
        return GraphQL::paginate('user');
    }
}
```

--------------------------------

### Register a schema programmatically

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/graphql.md

Example of registering a custom schema using GraphQL::addSchema and buildSchemaFromConfig. The query and types arrays reference class strings; mutation is empty.

```php
use Rebing\GraphQL\Support\Facades\GraphQL;

GraphQL::addSchema('custom', GraphQL::buildSchemaFromConfig([
    'query' => [\App\GraphQL\Queries\UsersQuery::class],
    'mutation' => [],
    'types' => [\App\GraphQL\Types\UserType::class],
]));
```

--------------------------------

### GraphQL query error handling example

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/graphql.md

Shows how to inspect the 'errors' key in the returned array. The result is always well-formed; errors are formatted arrays, not GraphQL\Error\Error instances.

```php
$result = GraphQL::query('{ user(id: "nope") { name } }', null, ['schema' => 'default']);

if (isset($result['errors'])) {
    foreach ($result['errors'] as $error) {
        // $error['message'], $error['extensions']['category'] etc.
        // note: this is a formatted array, not a GraphQL\Error\Error instance
    }
}
$data = $result['data'] ?? null;
```

--------------------------------

### type() lookup example

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/graphql.md

Shows how to use `GraphQL::type` with various modifier shorthands. Returns the webonyx type, applying each modifier wrapper from right to left. Throws `TypeNotFound` for unknown names.

```php
use GraphQL\Type\Definition\Type as GraphQLType;

$userType  = GraphQL::type('user');        // ObjectType
$listOf    = GraphQL::type('[user]');      // ListOfType
$nonNull   = GraphQL::type('user!');       // NonNull
$complex   = GraphQL::type('[user!]!');    // NonNull(ListOfType(NonNull(ObjectType)))
```

--------------------------------

### RoleType example extending EnumType

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/type.md

Example of a custom enum type. Defines values for ADMIN and USER roles with corresponding string values.

```php
namespace App\GraphQL\Enums;

use Rebing\GraphQL\Support\EnumType;

class RoleType extends EnumType
{
    protected $attributes = [
        'name' => 'Role',
        'values' => [
            'ADMIN' => ['value' => 'admin'],
            'USER' => ['value' => 'user'],
        ],
    ];
}
```

--------------------------------

### Generated Query stub output

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/console-commands.md

Example of a generated query class stub from the make:graphql:query command. It includes a default 'user' name, a list of strings return type, empty args, and a resolve method returning a placeholder array.

```php
<?php

declare(strict_types=1);

namespace App\GraphQL\Queries;

use GraphQL\Type\Definition\Type;
use GraphQL\Type\Definition\ResolveInfo;
use Rebing\GraphQL\Support\Query;

class UserQuery extends Query
{
    protected $attributes = [
        'name' => 'user',
        'description' => 'A query'
    ];

    public function type(): Type
    {
        return Type::listOf(Type::string());
    }

    public function args(): array
    {
        return [

        ];
    }

    public function resolve($root, array $args, $context, ResolveInfo $resolveInfo)
    {
        return [
            'The user works',
        ];
    }
}
```

--------------------------------

### Create middleware with make:graphql:middleware Artisan command

Source: https://github.com/rebing/graphql-laravel/blob/master/README.md

Run this Artisan command to generate a new resolver middleware class in app/GraphQL/Middleware.

```sh
php artisan make:graphql:middleware ResolvePage
```

--------------------------------

### Example of implementing UnionType

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/type.md

Example implementation of UnionType for a SearchResult union. types() returns user and post types; resolveType selects based on the root's 'type' key.

```php
namespace App\GraphQL\Unions;

use GraphQL\Type\Definition\Type;
use Rebing\GraphQL\Support\Facades\GraphQL;
use Rebing\GraphQL\Support\UnionType;

class SearchResultType extends UnionType
{
    protected $attributes = ['name' => 'SearchResult'];

    public function types(): array
    {
        return [GraphQL::type('user'), GraphQL::type('post')];
    }

    public function resolveType($root)
    {
        return $root['type'] === 'user' ? GraphQL::type('user') : GraphQL::type('post');
    }
}
```

--------------------------------

### Short-circuit middleware example

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/middleware.md

Middleware that throws AuthorizationError if no user context, never calling $next.

```php
class GuardedFieldMiddleware extends Middleware
{
    public function handle(mixed $root, array $args, mixed $context, ResolveInfo $info, Closure $next): mixed
    {
        if (($context->user ?? null) === null) {
            throw new \Rebing\GraphQL\Error\AuthorizationError('Not allowed');
        }

        return $next($root, $args, $context, $info);
    }
}

```

--------------------------------

### Per-schema override to disable tracing

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/tracing.md

Example of disabling tracing for a specific schema by setting 'tracing' to false in the schema configuration.

```php
// per-schema override
'schemas' => [
    'default' => [
        'query' => [/* ... */],
        'tracing' => false, // disable tracing for this schema
    ],
],
```

--------------------------------

### boot method signature

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/service-provider.md

Public method that registers config publishing and routes. Called during service provider boot.

```php
public function boot(): void
```

--------------------------------

### Vanilla JavaScript file upload - HTML input

Source: https://github.com/rebing/graphql-laravel/blob/master/README.md

HTML file input element used in the vanilla JavaScript example. It is referenced by id 'fileUpload'.

```html
<input type="file" id="fileUpload">
```

--------------------------------

### Review configuration file

Source: https://github.com/rebing/graphql-laravel/blob/master/README.md

The published configuration file is located at config/graphql.php. Review it to adjust package settings.

```text
config/graphql.php
```

--------------------------------

### GraphQL mutation query

Source: https://github.com/rebing/graphql-laravel/blob/master/README.md

Example GraphQL query to invoke the updateUserPassword mutation with id and password arguments, requesting the id and email fields in the response.

```graphql
mutation users {
    updateUserPassword(id: "1", password: "newpassword") {
        id
        email
    }
}
```

--------------------------------

### Generate BookType with artisan make:graphql:type

Source: https://github.com/rebing/graphql-laravel/blob/master/README.md

Scaffolds a new GraphQL type class. Run this command to create the initial file for a type.

```bash
php artisan make:graphql:type BookType
```

--------------------------------

### Enable OpenTelemetry tracing driver with include_document option

Source: https://github.com/rebing/graphql-laravel/blob/master/README.md

Configures the tracing driver to use OpenTelemetryTracingDriver. The include_document option includes the GraphQL document in spans, which may contain sensitive data. Without an OTel SDK, spans are no-ops.

```php
'tracing' => [
    'driver' => \Rebing\GraphQL\Support\Tracing\OpenTelemetryTracingDriver::class,
    'driver_options' => [
        // Include the GraphQL document in spans (may contain sensitive data)
        'include_document' => true,
    ],
],
```

--------------------------------

### Publish configuration file via artisan

Source: https://github.com/rebing/graphql-laravel/blob/master/README.md

Publishes the package's configuration file using the Laravel artisan vendor:publish command.

```bash
php artisan vendor:publish --provider="Rebing\GraphQL\GraphQLServiceProvider"
```

--------------------------------

### Remove $getSelectFields from authorize()

Source: https://github.com/rebing/graphql-laravel/blob/master/UPGRADE.md

The optional Closure $getSelectFields parameter has been removed from Field::authorize(). Remove it from your authorize() overrides.

```diff
-public function authorize($root, array $args, $ctx, ?ResolveInfo $resolveInfo = null, ?Closure $getSelectFields = null): bool
+public function authorize($root, array $args, $ctx, ?ResolveInfo $resolveInfo = null): bool
```

--------------------------------

### Using field arguments in a privacy check

Source: https://github.com/rebing/graphql-laravel/blob/master/README.md

Access field arguments in the privacy closure via $args. This example only allows access when the 'reason' argument is 'legal' or 'compliance'.

```php
'ssn' => [
    'type'    => Type::string(),
    'args'    => [
        'reason' => [
            'type' => Type::nonNull(Type::string()),
        ],
    ],
    'privacy' => function (mixed $root, array $args, $ctx): bool {
        // Only allow access when a valid reason is provided.
        return in_array($args['reason'] ?? '', ['legal', 'compliance']);
    },
],
```

--------------------------------

### PHPDoc for complex types

Source: https://github.com/rebing/graphql-laravel/blob/master/CONTRIBUTING.md

Use generic syntax for arrays and collections in PHPDoc annotations. Examples show array, list, and parameter type hints.

```php
/** @var array<string,mixed> */
/** @var list<object> */
/** @param array<string,Schema> $schemas */
```

--------------------------------

### isReadOnly

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/operation-params.md

Returns whether the underlying operation was submitted via a read-only HTTP method. This flag is set by the request parser for GET requests.

```APIDOC
## isReadOnly

### Description
Returns whether the underlying operation was submitted via a read-only HTTP method. This flag is set by the request parser for GET requests.

### Method
isReadOnly

### Parameters
None

### Returns
bool - True if the operation was submitted via a read-only HTTP method, false otherwise.

### Example
```php
$params->isReadOnly(); // false
```
```

--------------------------------

### ReadOnlyOperationMiddleware handle signature

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/execution-middleware.md

Opt-in middleware that rejects non-query operations on GET requests. Must be listed after AutomaticPersistedQueriesMiddleware to avoid missing query errors.

```php
public function handle(string $schemaName, Schema $schema, OperationParams $params, $rootValue, $contextValue, Closure $next): ExecutionResult
```

--------------------------------

### Console commands for generating GraphQL classes

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/console-commands.md

Shows all available artisan make:graphql commands for generating queries, mutations, types, inputs, enums, interfaces, unions, fields, middleware, execution middleware, scalars, and schema config classes. The --oneof option on the input command flips 'isOneOf' to true.

```bash
php artisan make:graphql:query UserQuery        # App\GraphQL\Queries\UserQuery, schema name "user"
php artisan make:graphql:mutation UpdateUserMutation # App\GraphQL\Mutations\UpdateUserMutation, schema name "updateUser"

# Types
php artisan make:graphql:type UserType          # App\GraphQL\Types\UserType
php artisan make:graphql:input CreateUserInput  # App\GraphQL\Inputs\CreateUserInput
php artisan make:graphql:input CreateUserInput --oneof   # generates a OneOf input type
php artisan make:graphql:enum RoleType          # App\GraphQL\Enums\RoleType
php artisan make:graphql:interface ContentInterface
php artisan make:graphql:union SearchResultType

# Reusable field / middleware / scalar
php artisan make:graphql:field SomeField
php artisan make:graphql:middleware LogField
php artisan make:graphql:executionMiddleware Timing
php artisan make:graphql:scalar DateTime

# Schema as a class (ConfigConvertible)
php artisan make:graphql:schemaConfig UserSchema
```

--------------------------------

### Enable OpenTelemetry tracing in config/graphql.php

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/tracing.md

Configuration to enable OpenTelemetry tracing driver with optional per-field spans and driver options. The 'include_document' option embeds the query string in spans, which is sensitive.

```php
// config/graphql.php
'tracing' => [
    'driver' => \Rebing\GraphQL\Support\Tracing\OpenTelemetryTracingDriver::class,
    'field_tracing' => true,           // optional per-field spans
    'driver_options' => [
        'include_document' => true,    // embeds the query string in spans (sensitive!)
    ],
],
```

--------------------------------

### OpenTelemetryTracingDriver constructor signature

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/tracing.md

Constructor for the OpenTelemetry tracing driver. Throws RuntimeException with a specific message if the open-telemetry/api package is missing. Obtains a tracer named 'rebing/graphql-laravel' and reads the include_document option from driverOptions.

```php
public function __construct(array $driverOptions = [])
```

--------------------------------

### Create a custom UserLoader class with deferred resolution

Source: https://github.com/rebing/graphql-laravel/blob/master/README.md

Defines a plain PHP class that accumulates keys and performs a single bulk query when triggered. Register it as a scoped singleton to ensure a fresh instance per request, safe for Laravel Octane and queue workers.

```php
declare(strict_types = 1);
namespace App\GraphQL\Loaders;

use App\Models\User;
use GraphQL\Deferred;

class UserLoader
{
    /** @var list<int> */
    private array $pendingIds = [];

    /** @var array<int,User> */
    private array $loaded = [];

    /**
     * Register a key to be loaded and return a deferred resolver.
     */
    public function load(int $id): Deferred
    {
        $this->pendingIds[] = $id;

        return new Deferred(function () use ($id): ?User {
            $this->loadPending();

            return $this->loaded[$id] ?? null;
        });
    }

    /**
     * Bulk-fetch all pending keys in a single query.
     */
    private function loadPending(): void
    {
        $ids = array_diff(array_unique($this->pendingIds), array_keys($this->loaded));
        $this->pendingIds = [];

        if ($ids === []) {
            return;
        }

        $users = User::whereIn('id', $ids)->get()->keyBy('id');

        foreach ($users as $id => $user) {
            $this->loaded[$id] = $user;
        }
    }
}
```

--------------------------------

### Execution middleware configuration with ReadOnlyOperationMiddleware

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/execution-middleware.md

Example config/graphql.php execution_middleware array. ReadOnlyOperationMiddleware must come after AutomaticPersistedQueriesMiddleware to prevent 'No GraphQL query available' errors.

```php
// config/graphql.php
'execution_middleware' => [
    \Rebing\GraphQL\Support\ExecutionMiddleware\ValidateOperationParamsMiddleware::class,
    \Rebing\GraphQL\Support\ExecutionMiddleware\AutomaticPersistedQueriesMiddleware::class,
    \Rebing\GraphQL\Support\ExecutionMiddleware\ReadOnlyOperationMiddleware::class, // AFTER APQ
    \Rebing\GraphQL\Support\ExecutionMiddleware\AddAuthUserContextValueMiddleware::class,
],
```

--------------------------------

### QueryMakeCommand class structure

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/console-commands.md

Illustrates the common structure of all generator commands. Declares the Symfony command name, artisan signature, description, and type, and overrides getStub(), getDefaultNamespace(), and buildClass() to replace the DummyGraphqlName placeholder with the lowercased name minus a trailing 'Query' suffix.

```php
<?php

#[AsCommand('make:graphql:query')]
class QueryMakeCommand extends GeneratorCommand
{
    protected $signature = 'make:graphql:query {name}';
    protected $description = 'Create a new GraphQL query class';
    protected $type = 'Query';

    protected function getStub(): string
    {
        return __DIR__ . '/stubs/query.stub';
    }

    protected function getDefaultNamespace($rootNamespace): string
    {
        return $rootNamespace . '\GraphQL\Queries';
    }

    protected function buildClass($name): string
    {
        $stub = parent::buildClass($name);

        return $this->replaceGraphqlName($stub);
    }

    protected function replaceGraphqlName(string $stub): string
    {
        $graphqlName = lcfirst($this->getNameInput());
        $graphqlName = \Safe\preg_replace('/Query$/', '', $graphqlName);

        return str_replace('DummyGraphqlName', $graphqlName, $stub);
    }
}
```

--------------------------------

### Register middleware on a specific query (UsersQuery)

Source: https://github.com/rebing/graphql-laravel/blob/master/README.md

Assign middleware to a specific query by listing classes in the $middleware property of the query class.

```php
declare(strict_types = 1);
namespace App\GraphQL\Queries;

use App\GraphQL\Middleware;
use Rebing\GraphQL\Support\Query;

class UsersQuery extends Query
{
    protected $middleware = [
        Middleware\Logstash::class,
        Middleware\ResolvePage::class,
    ];
}
```

--------------------------------

### CsrfGuard::using() in schema configuration

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/csrf-guard.md

Example of using the middleware in a per-schema configuration within config/graphql.php. Shows how to set the middleware for the default schema.

```php
// config/graphql.php
'schemas' => [
    'default' => [
        'query' => [/* ... */],
        'middleware' => [
            \Rebing\GraphQL\Support\Middleware\CsrfGuard::using(strictWhenAmbiguous: false),
        ],
    ],
],
```

--------------------------------

### Update privacy closure signature

Source: https://github.com/rebing/graphql-laravel/blob/master/UPGRADE.md

Privacy closures now receive $root as the first argument, followed by $args, $context, and optional $resolveInfo.

```diff
-'privacy' => function (array $args, $ctx): bool {
+'privacy' => function (mixed $root, array $args, $ctx, ?ResolveInfo $info = null): bool {
```

--------------------------------

### Run the full test suite

Source: https://github.com/rebing/graphql-laravel/blob/master/CONTRIBUTING.md

Runs all tests via paratest in parallel. The suite includes TestCase and TestCaseDatabase base classes.

```bash
composer tests
```

--------------------------------

### registerGraphQL method signature

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/service-provider.md

Public method that binds GraphQL as a singleton, aliases it as 'graphql', registers TracingManager, and sets up boot callbacks.

```php
public function registerGraphQL(): void
```

--------------------------------

### args method signature

Source: https://github.com/rebing/graphql-laravel/blob/master/_autodocs/api-reference/field.md

Returns an array of argument DSL entries. Default is [].

```php
/** @return array<string,array<string,mixed>> */
public function args(): array
```
Tokens:
Raw