GraphQL in Laravel done right

Recently a new package has revolutionised the creation of a GraphQL API in Laravel. This package makes it so simple and easy to setup a GraphQL server, that it gives you the same feeling you had first time you worked with Laravel, “What magic is this!”. This package is of course Lighthouse.
In This article I will cover how to set it up with a simple example with support for Relay, I assume you already know how GraphQL and Relay works.

This article was written on a older Ligthouse version, and it therefore might not work anymore. I’ll recommend you to follow the new offical tutorial, which can be found here.


For getting started simply add the package via composer and publish the config file.

Getting started

Now for the intersting part.
When setting up this package, we just have to create the following file `routes/graphql/schema.graphql`. This file is the one containing our whole schema for the graphql server. 
To get started we will add a simple endpoint for getting all posts in our database, for doing this we first need to create our Article type in the schema file.

Here we ended up creating two types, a type for articles and one for users, so we can get the author of the post. However we still don’t have any endpoints, so let’s add one in the schema file.

So here some more magic is happening, we are adding a custom directive called paginate this directive adds pagination for the given model supplied (in this case Article). We are also saying it should use the type connection which will result in it making the pagination relay compatible (this will be renamed to relay in next version). This results in the two following queries

Screenshot from GraphiQL

Looking into the node query for relay, we see that Article and User isn’t inside here, so we need some custom directives on these too. By adding the model directive to each of them, it now knows that it should treat them as an implementation of Node. We also added the globalId directive, this will automatically convert the id to a base:64 unique global id.

Types with directives added

Looking into the generated endpoint for node now, it contains our Article and User .

Screenshot from GraphiQL

Let’s create our models and migrations. Lighthouse is looking for the models inside app/models so let’s add Article in the folder and move User inside there also.

Great! Let’s migrate the database and try out our new API.

Screenshot from GraphiQL

The endpoint worked, but we have no data in our database, let’s add some data manually first and later figure out how to do it with through GraphQL.

Screenshot from GraphiQL with articles

Now we can see some data! Let’s add so we can get all the articles from a author. For doing this we just add the relationship to our User definition and we can now get all the articles from an author.

Screenshot from GraphiQL

Now let’s add a mutator for creating a new article, this endpoint will also need authentication, as we of course need to be a user in the system before we can create a new article.

Before we can use this, we need to configure the TokenGuard, to do this we just have to add the api_token field to the User and we are good to go.

We manually add a token in the database (you can create your own UI for setting the token or use Laravel Passport), and use this token for authenticating.

Screenshot from GraphiQL

We now have a new article and we can see that the author whom made it was our authenticated user. So now we have a really simple GraphQL API up and running, but with support for getting our articles and creating them, and then API has full support for Relay!

Hope you enjoyed this post, and if you would like to know more visit Lighthouse documentation. You can also find the example created above on Github.