Butler GraphQL

https://github.com/glesys/butler-graphql
Admin
Butler GraphQL is an opinionated package for Laravel that simplifies the creation of GraphQL APIs,...
Tokens:3,001
Snippets:21
Trust Score:7.7
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Butler GraphQL Package with Composer

Source: https://github.com/glesys/butler-graphql/blob/main/README.md

This command installs the `glesys/butler-graphql` package into a PHP project using Composer, a dependency manager for PHP. It's the first step to integrate the GraphQL package into a Laravel or Lumen application.

```bash
composer require glesys/butler-graphql
```

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

### Install Laravel Debugbar for Development

Source: https://github.com/glesys/butler-graphql/blob/main/README.md

Installs the `barryvdh/laravel-debugbar` package as a development dependency, enabling additional debugging features for Butler GraphQL responses when `APP_DEBUG` is true.

```Shell
composer require barryvdh/laravel-debugbar --dev
```

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

### Updating Butler\Graphql\DataLoader Constructor in PHP

Source: https://github.com/glesys/butler-graphql/blob/main/UPGRADE.md

The constructor signature for `Butler\Graphql\DataLoader` has changed. If you manually instantiate this class, you no longer need to provide a `React\EventLoop\LoopInterface` instance. This simplifies the instantiation process.

```php
$dataLoader = new DataLoader($this->getLoop());
```

```php
$dataLoader = new DataLoader();
```

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

### Migrating Promise Handling from react/promise to amphp/amp in PHP

Source: https://github.com/glesys/butler-graphql/blob/main/UPGRADE.md

When upgrading Butler-GraphQL, the underlying promise library changes from `react/promise` to `amphp/amp`. This requires replacing `->then()` calls with the `yield` keyword for promise resolution in your resolvers. This change affects how asynchronous operations are handled.

```php
public function topVotedComment(Article $source, $args, $context, $info)
{
    return $context['loader'](Closure::fromCallable([$this, 'loadComments']))
        ->load($source->id)
        ->then(function ($articleComments) {
            return collect($articleComments)->sortByDesc('votes')->first();
        });
}
```

```php
public function topVotedComment(Article $source, $args, $context, $info)
{
    $comments = yield $context['loader'](Closure::fromCallable([$this, 'loadComments']))
        ->load($source->id);

    return collect($comments)->sortByDesc('votes')->first();
}
```

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

### Bash Publish Butler GraphQL Configuration

Source: https://github.com/glesys/butler-graphql/blob/main/README.md

Provides the Artisan command to publish Butler GraphQL's default configuration file. This allows developers to customize settings that override the convention-over-configuration defaults.

```bash
php artisan vendor:publish
```

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

### Butler GraphQL Resolver Method Parameters

Source: https://github.com/glesys/butler-graphql/blob/main/README.md

This API documentation describes the standard parameters passed to all resolving methods within the Butler GraphQL package. These parameters provide access to the root value, arguments, context, and resolve information, enabling flexible data fetching and manipulation.

```APIDOC
Resolver Method Signature:
/**
 * @param  mixed  $root
 * @param  array  $args
 * @param  array  $context
 * @param  \GraphQL\Type\Definition\ResolveInfo  $info
 */

Parameters:
- $root (mixed): The object that contains the result of the parent field. For a top-level query, this is typically null.
- $args (array): An associative array of arguments passed to the field in the GraphQL query.
- $context (array): A value that is passed to every resolver and can hold important contextual information like the currently logged-in user, database connection, etc.
- $info (\GraphQL\Type\Definition\ResolveInfo): An object containing information about the execution state of the query, including the field name, path, and schema.
```

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

### PHP GraphQL N+1 Data Loading with Context Loader

Source: https://github.com/glesys/butler-graphql/blob/main/README.md

Demonstrates the use of Butler GraphQL's built-in data loader, available via `$context['loader']`, to efficiently load nested data and prevent N+1 query issues. It shows how to define a batch function for loading related comments for multiple articles.

```php
<?php

namespace App\Http\Graphql\Types;

use App\Models\Article;

class Article
{
    public function comments(Article $source, $args, $context, $info)
    {
        return $context['loader'](function ($articleIds) {
            return Comment::whereIn('article_id', $articleIds)
                ->cursor()
                ->groupBy('article_id');
        }, [])->load($source->id);
    }
}
```

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

### Butler GraphQL Configuration Variables

Source: https://github.com/glesys/butler-graphql/blob/main/README.md

Environment variables used to configure Butler GraphQL's schema extension paths and debugging behavior.

```APIDOC
BUTLER_GRAPHQL_SCHEMA_EXTENSIONS_PATH
  - Description: Specifies the directory path where partial GraphQL schema files are located.
  - Default: app_path('Http/Graphql/')

BUTLER_GRAPHQL_SCHEMA_EXTENSIONS_GLOB
  - Description: Defines the glob pattern to match partial GraphQL schema files within the extensions path.
  - Default: 'schema-*.graphql'

BUTLER_GRAPHQL_INCLUDE_DEBUG_MESSAGE
  - Description: Controls whether the real error message is included in GraphQL error responses.
  - Default: false (Set to true to include)

BUTLER_GRAPHQL_INCLUDE_TRACE
  - Description: Controls whether stack traces are included in GraphQL error responses.
  - Default: false (Set to true to include)
```

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

### Implement PHP Query Resolver for Pending Signups

Source: https://github.com/glesys/butler-graphql/blob/main/README.md

This PHP class `PendingSignups` acts as a resolver for the `pendingSignups` GraphQL query. It uses the `__invoke` magic method to define the resolution logic, querying `Signups` where the status is 'pending'. This demonstrates how to fetch data for a GraphQL query.

```php
<?php

namespace App\Http\Graphql\Queries;

class PendingSignups
{
    public function __invoke($root, $args, $context)
    {
        return Signups::where('status', 'pending')->get();
    }
}
```

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

### Create Laravel Controller for GraphQL Requests

Source: https://github.com/glesys/butler-graphql/blob/main/README.md

This Laravel controller `GraphqlController` integrates the `HandlesGraphqlRequests` trait provided by the Butler GraphQL package. This trait provides the necessary logic to handle incoming GraphQL API requests, making the controller responsible for processing GraphQL operations.

```php
<?php

namespace App\Http\Controllers;

use Butler\Graphql\Concerns\HandlesGraphqlRequests;

class GraphqlController extends Controller
{
    use HandlesGraphqlRequests;
}
```

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

### Define GraphQL Schema for Queries and Types

Source: https://github.com/glesys/butler-graphql/blob/main/README.md

This GraphQL schema defines a `Query` type with a `pendingSignups` field, which returns a list of `Signup` objects. The `Signup` type includes `email` and `verificationToken` fields, both marked as non-nullable. This schema forms the basis for the GraphQL API structure.

```graphql
type Query {
    pendingSignups: [Signup!]!
}

type Signup {
    email: String!
    verificationToken: String!
}
```

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

### PHP GraphQL Shared Data Loaders for Reusable Logic

Source: https://github.com/glesys/butler-graphql/blob/main/README.md

Illustrates how to create and reuse a shared data loader function across multiple resolvers to avoid code duplication and optimize database interactions. This pattern ensures the batch loading logic is executed only once, even if multiple fields request the same data.

```php
<?php

namespace App\Http\Graphql\Types;

use App\Models\Article;
use Closure;

class Article
{
    public function comments(Article $source, $args, $context, $info)
    {
        return $context['loader'](Closure::fromCallable([$this, 'loadComments']), [])
            ->load($source->id);
    }

    public function topVotedComment(Article $source, $args, $context, $info)
    {
        $comments = yield $context['loader'](Closure::fromCallable([$this, 'loadComments']))
            ->load($source->id);

        return collect($comments)->sortByDesc('votes')->first();
    }

    private function loadComments($articleIds)
    {
        return Comment::whereIn('article_id', $articleIds)
            ->cursor()
            ->groupBy('article_id');
    }
}
```

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

### Implement PHP Type Field Resolver for Signup Verification Token

Source: https://github.com/glesys/butler-graphql/blob/main/README.md

This PHP class `Signup` defines a resolver for the `verificationToken` field within the `Signup` GraphQL type. It demonstrates how to resolve a specific field by accessing a property (`token`) from the source object (`$source`), allowing for custom logic for individual fields.

```php
<?php

namespace App\Http\Graphql\Types;

class Signup
{
    public function verificationToken($source, $args, $context, $info)
    {
        return $source->token;
    }
}
```

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

### Butler GraphQL Configuration Variables

Source: https://github.com/glesys/butler-graphql/blob/main/README.md

Details the environment variables available for customizing Butler GraphQL's behavior. These variables allow overriding default paths for the GraphQL schema file and the base namespace for GraphQL resolvers and types.

```APIDOC
BUTLER_GRAPHQL_SCHEMA
  - Description: Specifies the absolute path to the main GraphQL schema file.
  - Default: `app_path('Http/Graphql/schema.graphql')`

BUTLER_GRAPHQL_NAMESPACE
  - Description: Defines the base PHP namespace for Butler GraphQL's generated classes and resolvers.
  - Default: `'App\\Http\\Graphql\\'`
```

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

### Implement Custom GraphQL Authorization Hook

Source: https://github.com/glesys/butler-graphql/blob/main/README.md

Demonstrates how to implement custom authorization logic for GraphQL requests using the `beforeExecutionHook` method within a Laravel controller. This method provides access to the GraphQL schema, query, operation name, and variables for inspection before execution.

```PHP
<?php

namespace App\Http\Controllers;

use Butler\Graphql\Concerns\HandlesGraphqlRequests;
use GraphQL\Type\Schema;
use GraphQL\Language\AST\DocumentNode;

class GraphqlController extends Controller
{
    use HandlesGraphqlRequests;

    /**
     * @param  $schema         A parsed version of your GraphQL schema
     * @param  $query          A parsed version of the consumer's query
     * @param  $operationName  The passed operation name (for when the query contains multiple operations)
     * @param  $variables      Any variables passed alongside the query
     */
    public function beforeExecutionHook(Schema $schema, DocumentNode $query, string $operationName = null, $variables = null): void
    {
        // TODO: Implement custom authorization logic here
    }
}
```

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

### GraphQL Schema Splitting with Extend Type

Source: https://github.com/glesys/butler-graphql/blob/main/README.md

Demonstrates how to modularize a large GraphQL schema by splitting it into multiple files. The `extend type` keyword is used to add fields to an existing type defined in a base schema file, promoting better organization and maintainability.

```graphql
type Query {
    users: [User!]!
}

type User {
    id: ID!
    username: String!
}
```

```graphql
extend type User {
    firstName: String
    lastName: String
    email: String!
}
```

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

### Butler GraphQL Callable Resolver Return Type

Source: https://github.com/glesys/butler-graphql/blob/main/README.md

This API documentation illustrates how a resolver method can return a callable function instead of a direct value. This allows for deferred execution of the resolution logic, providing more control over when and how data is fetched, especially useful for complex or asynchronous operations.

```APIDOC
Callable Resolver:
public function __invoke()
{
    return function ($root, $args, $context, $info) {
        // Resolution logic here
    };
}

Return Value:
- callable: A function that will be invoked with the same set of parameters ($root, $args, $context, $info) when the field needs to be resolved.
```

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

### Define Laravel Route for GraphQL Endpoint

Source: https://github.com/glesys/butler-graphql/blob/main/README.md

This PHP code defines a POST route `/graphql` in Laravel, mapping it to the `GraphqlController`. This route serves as the primary endpoint for all GraphQL API interactions, directing incoming requests to the controller equipped to handle them.

```php
$router->post('/graphql', GraphqlController::class);
```

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

### PHP GraphQL Interface Resolution with __typename

Source: https://github.com/glesys/butler-graphql/blob/main/README.md

Demonstrates how to explicitly specify the concrete type for an interface field by including a `__typename` key in the returned data array. This helps Butler GraphQL correctly resolve the type for interface implementations.

```php
<?php

namespace App\Http\Graphql\Types;

class Post
{
    public function attachment($source, $args, $context, $info)
    {
        return [
            '__typename' => 'Photo',
            'height' => 200,
            'width' => 300,
        ];
    }
}
```

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

### PHP GraphQL Type Resolution for Queries and Mutations

Source: https://github.com/glesys/butler-graphql/blob/main/README.md

Explains how to define a `resolveType` method for top-level queries and mutations. This method is responsible for resolving the concrete type of the returned data, allowing for polymorphic results from a single query or mutation.

```php
<?php

namespace App\Http\Graphql\Queries;

use App\Attachment;

class Attachments
{
    public function __invoke($source, $args, $context, $info)
    {
        return Attachment::all();
    }

    public function resolveType($source, $context, $info)
    {
        return $source->type; // `Photo` or `Video`
    }
}
```

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

### PHP GraphQL Dynamic Interface Type Resolution with resolveTypeForField

Source: https://github.com/glesys/butler-graphql/blob/main/README.md

Illustrates how to dynamically determine the concrete type for an interface field by implementing a `resolveTypeFor[Field]` method in the parent resolver. This method inspects the source data to return the appropriate type name (e.g., 'Photo' or 'Video').

```php
<?php

namespace App\Http\Graphql\Types;

class Post
{
    public function attachment($source, $args, $context, $info)
    {
        return [
            'height' => 200,
            'width' => 300,
        ];
    }

    public function resolveTypeForAttachment($source, $context, $info)
    {
        if (isset($source['height'], $source['width'])) {
            return 'Photo';
        }
        if (isset($source['length'])) {
            return 'Video';
        }
    }
}
```
Tokens:
Raw