Creating Your First GraphQL Schema and Understanding Types, Queries, and Mutations in Laravel GraphQL



GraphQL is a powerful API query language that allows clients to request specific data and only what they need. Laravel integrates well with GraphQL using packages like **Rebing GraphQL**, enabling you to define schemas, queries, and mutations with ease. In this article, we’ll walk through creating your first GraphQL schema in Laravel and understanding the fundamental concepts of types, queries, and mutations.


Key Concepts in GraphQL


Before diving into the Laravel setup, it’s important to understand the building blocks of GraphQL:


Schema: Defines the structure of your API. It is a contract between the client and the server, specifying the types of data that can be queried or mutated.

Types: Represent the shape of data returned by queries or used in mutations. You define different types for different data structures.

Queries: Read operations in GraphQL. A query fetches data based on the client’s request.

Mutations: Write operations that modify data on the server. Mutations are used for tasks like creating, updating, or deleting data.


Step-by-Step Guide to Creating a GraphQL Schema in Laravel


1. Prerequisites


Ensure you have the following before you begin:


  • A Laravel project set up. If not, you can create one using:


  composer create-project --prefer-dist laravel/laravel graphql-demo


  • Composer installed for dependency management.

  

2. Installing Rebing GraphQL Package


To integrate GraphQL into Laravel, you can use the Rebing GraphQL package. First, install the package:


composer require rebing/graphql-laravel


After the package is installed, publish the configuration file using:


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


This command generates the `config/graphql.php` file, which will be used to configure your GraphQL API.


3. Defining Your First GraphQL Schema


In `config/graphql.php`, you'll define your schema, including the available queries and mutations.


Here’s an example of how the configuration looks:


return [
    'schema' => [
        'default' => [
            'query' => [
                'user' => App\GraphQL\Queries\UserQuery::class,
            ],
            'mutation' => [
                'createUser' => App\GraphQL\Mutations\CreateUserMutation::class,
            ],
        ],
    ],
];


This defines a default schema with one query (`UserQuery`) and one mutation (`CreateUserMutation`).


4. Defining GraphQL Types


Types define the structure of the data that can be queried or mutated. For example, if you want to query for user data, you need to define a `UserType`.


Create the `UserType` in `app/GraphQL/Types/UserType.php`:


namespace App\GraphQL\Types;

use Rebing\GraphQL\Support\Type as GraphQLType;
use GraphQL\Type\Definition\Type;

class UserType extends GraphQLType
{
    protected $attributes = [
        'name' => 'User',
        'description' => 'A type that describes a user',
    ];

    public function fields(): array
    {
        return [
            'id' => [
                'type' => Type::nonNull(Type::int()),
                'description' => 'The ID of the user',
            ],
            'name' => [
                'type' => Type::string(),
                'description' => 'The name of the user',
            ],
            'email' => [
                'type' => Type::string(),
                'description' => 'The email of the user',
            ],
        ];
    }
}


Now, register this type in `graphql.php`:


'types' => [
    'User' => App\GraphQL\Types\UserType::class,
],


This `UserType` defines the shape of a user, including fields like `id`, `name`, and `email`.


5. Creating Your First Query


Next, let’s create a query to fetch users. Queries allow the client to request data. 


Create the `UserQuery` in `app/GraphQL/Queries/UserQuery.php`:


namespace App\GraphQL\Queries;

use GraphQL\Type\Definition\Type;
use Rebing\GraphQL\Support\Query;
use App\Models\User;

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

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

    public function resolve($root, $args)
    {
        return User::all();
    }
}


In this query, we define that it will return a list of `UserType`, and the `resolve` function will fetch all users from the database.


6. Creating a Mutation


Mutations are similar to queries but are used to perform operations like creating, updating, or deleting data.


Create the `CreateUserMutation` in `app/GraphQL/Mutations/CreateUserMutation.php`:


namespace App\GraphQL\Mutations;

use GraphQL\Type\Definition\Type;
use Rebing\GraphQL\Support\Mutation;
use App\Models\User;

class CreateUserMutation extends Mutation
{
    protected $attributes = [
        'name' => 'createUser',
    ];

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

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

    public function resolve($root, $args)
    {
        return User::create([
            'name' => $args['name'],
            'email' => $args['email'],
        ]);
    }
}


This mutation allows clients to create new users by passing in `name` and `email` as arguments.


7. Testing Your GraphQL Queries and Mutations


You can now test your GraphQL setup by sending requests to the `/graphql` endpoint of your Laravel application.


To query all users, you can run:


{
    user {
        id
        name
        email
    }
}


To create a new user, use the following mutation:


mutation {
  createUser(name: "John Doe", email: "john@example.com") {
    id
    name
    email
  }
}


You can test this using tools like Postman, Insomnia, or GraphiQL.


GraphQL offers flexibility and efficiency in querying data. By understanding the core concepts like schemas, types, queries, and mutations, you can build powerful APIs that allow clients to fetch exactly the data they need. With Laravel’s ease of use and the Rebing GraphQL package, integrating GraphQL into your Laravel application is straightforward.


This guide covers the basics of setting up your first schema, defining types, and creating queries and mutations. From here, you can expand your GraphQL API by adding more complex queries, pagination, authorization, and error handling to meet your application's needs.