GraphQL is a query language for your API. It simplifies the process of requesting the server by providing convenient ways to query objects.
For instance, if you’re using a REST API and you need a list of books, you might hit the GET /books/list
endpoint for all books. Then if you need a specific book by ID, you would hit GET /book?id={id}
, which means you’ll be making multiple requests to the server.
But GraphQL does something called declarative data fetching, where you can ask for what you want and get a predictable result in a single request.
Awesome right? Let’s see how it all works.
What we will be learning?
In this article, you’ll learn the basics of GraphQL by using the Laravel GraphQL package to build a server that does the following:
Before we get started, let’s go over some GraphQL fundamentals.
What is a GraphQL Schema?
A GraphQL schema describes queries, mutations, and types associated with it:
In the code above, the exclamation mark on column names such as id
, name
, and email
means that they are required fields.
You can also define various data types such as Int
, String
, and so on. You can also include list types and define the data type it should contain like with hobbies
.
What are GraphQL Queries?
GraphQL makes it convenient to interact with data on an object. You use methods to ask for specific fields on objects and then get the expected results:
What are GraphQL Resolvers?
Every time you request data from a GraphQL server, it gets resolved
.
Resolvers contain arguments such as an object
, args
, context
, and info
. You’ll see how resolvers work while building this project.
How to Get Started with GraphQL
Set up a Laravel environment by running this command in the terminal:
If you don’t have composer installed, you can get it from here.
Install the open-source graphql-laravel server package:
Once the installation is finished, publish config/graphql.php
:
And start the development server with php artisan serve
:
How to Create the Migration, Controllers, and Resource
In this section, you’ll create a relationship between users and posts.
To do this, you’ll need to create models where you define the relationship between the entities, create migrations, and define database schemas.
In app/Models/User
, create a hasMany
relationship between users and posts:
And in app/models/Post
, define a relationship to map users to posts:
How to Create the Migration
In this section you’ll create the migration.
Laravel already ships with a default User migration. All you need to do now is add a migration for posts:
This creates a migration file with the database/migrations
direction. Within the migration file, define the schema:
Next, modify the existing .env
to name the database and establish a connection:
Run the migrate command to create the User
and Post
tables:
You can generate random records for the User
and Post
tables using Laravel factories.
Since Laravel ships with a default User
factory, you can use that and focus on creating a Post
factory.
How to Create a Post Factory
Once PostFactory
gets created within the database > factories
directory, you’ll have to define the column names and the fakers you need within the definition method
:
How to Make the Database Seeder
Within the seeder class, create an execution instance for both User
and Post
factories.
This will create five users and five posts with corresponding user_id
‘s:
Then run the artisan seeder command:
Once you run that command in the terminal, check the database tables (User
and Post
):
How to Create a User Query
As of the time of writing this article, the Laravel GraphQL package doesn’t support creating a scaffold for queries via the terminal.
So add the following to app > GraphQL > Type > UserType.php
:
In the code snippet above, you add the namespace you need to the User
model. You also include a protected $attributes array
that describes the model.
You also added a public field
function that returns an array.
Within this function, you define the schema to include columns you specified in the user table (id, name, email)
.
Type::nonNull(Type::string())
is the exclamation mark indicating the required fields and string data type.
How to Add a Type to the Config
Add the UserType
to the config file you created earlier: app > config > graphql.php
:
How to Define the User Query
Next, you’ll need to define a query that returns the UserType
or a list. You also need to specify the arguments you’ll use within the resolve method:
In the snippet above, you use the required namespace the package ships with together with App\Models\User
.
You also extend the GraphQLType
from the Laravel package, and define the attributes
as a protected array.
The args
method returns an ID, name, and email from the User
model.
The resolve method is used to retrieve the data from the database. If there are args
, then the if
block gets executed and helps you filter based on user requests.
Otherwise, all the data from the User
model is retrieved.
How to Add a Query to the Config
Add the following query to the app > config > graphql.php
configurations file:
You should now be able to query data from this endpoint: http://localhost:8000/graphql.
And in case you’re curious, /graphql
is the prefix for the route.
How to Query to Fetch all Users
For this query:
Here’s the expected output with Postman:
How to Create a Post Relationship with the User
Now you need to define a PostType
.
This approach follows what you defined earlier for UserType
.
Navigate to app > Type > PostType.php
and add the following:
Post
follows the specification defined for User
. Here you also used the namespace of the query, and also used the Post
model.
With the code above, you extend the Query on the PostQuery
class and set the $attributes
array to be protected. And you have a fields
function that returns and array with the ID, title, and comment.
Finally, you have a type
within the args
function that shows their various data types int
or string
with a description that tells you what they do at a glance.
How to Create a PostsQuery
Add the following to app > GraphQL > Query > PostsQuery.php
:
In the code above, you use the resolve method to retrieve data from the database like I mentioned earlier.
If there are args
, then the if
block gets executed and helps you filter based on the user request. Otherwise, all the data from the Post
model is returned.
How to Add PostsQuery and PostType to Config
Now you can use the following query to get all posts:
You can also fetch users with post relationships with this query:
How to Create a Mutation
Now you’ll set up a mutation to create a user. This mutation will help with operations that involve modifying state on the server.
In your case you’ll be mutating the state of the server by creating a user.
Create a mutation folder within the app directory, app > Mutation > CreateUserMutation.php
.
Then add the following code to CreateUserMutation.php
:
The resolve
method helps users of the application sign up and create their record. resolve
accepts args
as a parameter and then uses the firstOrCreate
method to ensure all users registering have a unique identifier, in this case, their email address.
In the config, you’ll also need to include the mutation you just created:
And here’s how to create a user:
Congrats! You’ve successfully built a GraphQL server using Laravel, and ran queries with Postman to get responses. Now that you know the basics of GraphQL, I hope you use it in your projects going forward.
All the code in this tutorial is available on GitHub, which also includes the Postman collection.
This content was originally published here.