Laravel GraphQL

To avoid the N+1 query problem, this library supports Dataloaders (deferred resolution).

Instead of fetching data immediately in a resolver, a Dataloader collects all requested keys during the execution phase. Once the execution reaches a point where it can no longer defer, the Dataloader fires a single batch request to the data source (Eloquent, API, Cache, etc.) using all collected keys. This is the recommended approach for most applications as it works with any data source.

When implementing a privacy callback (closure or class), you have access to four parameters:

• $root: The parent object being resolved (e.g., an Eloquent model instance). This allows for per-row privacy decisions.
• $args: The arguments declared specifically on the field itself. These are not the root query/mutation arguments.
• $ctx: The query context value. By default, the AddAuthUserContextValueMiddleware sets this to the authenticated user model (Auth::user()) or null.
• $info: (Optional) The GraphQL\Type\Definition\ResolveInfo object.

When using sibling-referencing rules (like prohibits, required_with, required_if, same, etc.) inside an InputType, the library automatically transforms these references into fully-qualified dot-notation paths. This ensures Laravel's Validator can correctly resolve the sibling field even when the input is nested or part of a list.

For example, if an InputType has a rule prohibits:mintParams on a field createParams, and that input is used in a list called recipients, the rule is automatically prefixed to recipients.0.mintParams.

To disable this automatic prefixing, override processCollectedRules() in your Query or Mutation class:

class MyMutation extends Mutation
{
    protected function processCollectedRules(array $rules): array
    {
        return $rules; // disable automatic cross-field rule prefixing
    }
}

The library supports three layers of middleware to intercept and mutate requests or responses:

1. HTTP Middleware: Standard Laravel HTTP middleware. Can be applied globally via graphql.route.middleware or per-schema via graphql.schemas.<yourschema>.middleware.
2. GraphQL Execution Middleware: Intercepts the processing of a GraphQL request. Configured via graphql.execution_middleware (global) or graphql.schemas.<yourschema>.execution_middleware (per-schema).
3. GraphQL Resolver Middleware: Executes for the specific query or mutation being targeted before the actual resolve() method is called.

It is important to distinguish between these two mechanisms:

• authorize(): Used on a Query or Mutation. It gates the entire operation. If it fails, the whole request is rejected with an error.
• privacy: Used on a Type field. It gates individual fields and silently returns null when denied. Use this for field-level visibility.

The library distinguishes between two types of errors:

1. Errors (Rebing\GraphQL\Error\*): Client-safe errors (like ValidationError or AuthorizationError) that appear in the GraphQL JSON response.
2. Exceptions (Rebing\GraphQL\Exception\*): Developer/configuration errors that are not included in GraphQL responses but are handled by Laravel's exception handler.

Customizing Error Handling

You can customize how errors are formatted for the client or how they are handled internally by providing class/method references in config/graphql.php.

// config/graphql.php

// Custom formatter: returns an array for each GraphQL\Error\Error
'error_formatter' => [App\GraphQL\ErrorFormatter::class, 'format'],

// Custom handler: receives all errors + the formatter
'errors_handler' => [App\GraphQL\ErrorHandler::class, 'handle'],

You can wrap types to add additional information to queries and mutations, similar to how pagination works. This allows you to return a wrapper object containing both the primary data and extra metadata (like messages or status info).

If you use the rebing/graphql-laravel-select-fields package, your wrapper class must implement the WrapType marker interface.

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"),
        ]),
    ];
}

When optimizing data fetching, choose between Dataloaders and the optional rebing/graphql-laravel-select-fields package based on your needs:

Note: These approaches are independent and can coexist.

In this library, types, queries, and mutations are defined using the $attributes property and methods like args() or fields(). These methods return configuration arrays where:

• The key is the name of the field or argument.
• type (required): A GraphQL specifier (e.g., Type::string()) defining the data type.
• description (optional): A string used for schema introspection.
• resolve (optional): An override for the default field resolver.
• deprecationReason (optional): A string explaining why a field is deprecated.