How to configure Laravel Lumen with Lighthouse PHP (GraphQL)
Recently I found an interesting package called Lighthouse PHP on the web.
Lighthouse is a PHP package that allows you to serve a GraphQL endpoint from your Laravel application. It greatly reduces the boilerplate required to create a schema, integrates well with any Laravel project, and is highly customizable giving you full control over your data.
Laravel Lumen is a stunningly fast micro-framework by Laravel.
Today, I decided to write a basic starter tutorial to configure Lighthouse PHP, because this package has Laravel as the main focus and I just passed some little traps in the way.
In this tutorial, I will not cover how to install Lumen micro-framework and composer. I suppose you already have a development environment “up and running”! If you don’t have it do it before…
For this tutorial, I have PHP 7.3.7, Composer 1.8.6 and Lumen (6.1.0).
So, let’s go!
At first, of course, we need to create a new application with Lumen before to install Lighthouse PHP via composer. Go to any directory on your machine and just run this command below to do this:
$ lumen new lighthouse-php-tutorial
Lighthouse PHP is a well-documented package and you can prefer to follow the detailed instructions on their website. But come back here later!…
Install dependencies
If all ok, you should get in this directory, and install the project dependencies like "nuwave/lighthouse" via composer.
$ composer require nuwave/lighthouse
Sometimes "composer require command" takes a lot of time to complete, when complete install packages, open this project in your preferred text editor, I prefer Visual Studio Code.
On Lumen, we have a "composer.json" file that describes all project dependencies, you should see "nuwave/lighthouse": "^4.3" as a child of "require" key.
Before all, let's get our Lumen application more complete using "Facades" and "Eloquent". Just open "bootstrap/app.php" and uncomment these lines as I did in the image below:
Now, we need to link "Nuwave\Lighthouse\LighthouseServiceProvider" in our application, on official Lighthouse documentation, just teaches to run "php artisan vendor:publish…" command but as we know, we don't have it on Lumen, unless you install this package.
I prefer not to install more dependency on this project, we be able to resolve this without any dependencies. "… less code, fewer bugs".
Well, to link “Nuwave\Lighthouse\LighthouseServiceProvider” go-to “bootstrap/app.php” add the code fragment before “Register Service Provider” and uncomment line 91 (after insert code fragment, otherwise line number is 79), see the images below:
Now we're able to register providers in a file located in the path "app/Providers/AppServicesProvider.php" for our application, do this exactly as I did on the image below:
Lighthouse provides some convenient artisan commands. All of them are namespaced under "lighthouse". Let's run "php artisan list" to check these commands, open your Terminal and type it:
$ php artisan list
Oh no! Dammit. Seems that we have a pitfall here… Lumen doesn't have "Target class [path.config]" and "Class path.config" neither. But, you remember what I said before "… I just passed some little traps in the way" and that it is!
But, if I writing this tutorial, I found a solution a this the main reason to share with you. Let's trait this, now we need to register instance container path, just open your "app/bootstrap.php" and add the code fragment before "Load The Application Routes" section as I did in the image below:
Now, let's check again running "php artisan list" command.
$ php artisan list
Configuration
Lighthouse comes with sensible configuration defaults and works right out of the box. Should you feel the need to change your configuration, you need to publish the configuration file first.
As we know, the artisan
command php artisan vendor:publish
will not work in Lumen without dependencies, so let's do this by hand!
Just create a config directory in your project.
$ mkdir ./config
And now, just copy "vendor/nuwave/lighthouse/config/config.php" into your "./config" directory as "lightghouse.php".
$ cp vendor/nuwave/lighthouse/config/config.php ./config/lighthouse.php
Open recently created file "config/lighthouse.php" and check "Schema Declaration" section (line 50). This is the base path where our default schema should be there.
Publish the default schema
Lighthouse includes a default schema to get you going right away. Publish it using the following artisan
command php artisan vendor:publish
will not work here too, then:
$ mkdir ./graphql
And now, just copy “vendor/nuwave/lighthouse/assets/default-schema.graphql” into your “./graphql” directory as “schema.graphql”.
$ cp vendor/nuwave/lighthouse/assets/default-schema.graphql ./graphql/schema.graphql
Extra
As described in the Lighthouse website you can "digging-deeper" to split your schema across multiple files and organize your types. (check how to do)
Using some tools like Postman (GraphQL BETA) or any other, you can't import schema used for Lighthouse, then you'll need a final schema.
I wrote a simple implementation for the command php artisan lighthouse:print-shema
to compile the final GraphQL schema and write the final schema string to a file (schema.graphql).
Serve the application
Well, here we go! Now that you’ve created your Lumen project with Lighthouse PHP up and running, it’s time to serve it and take a look at your work so far.
At first, configure your .env file, database, phpunit like you always do in a project Lumen. Wait, if you don't know how to do this, visit the Lumen website or search for beginner tutorials for this.
Type the following on your command prompt in the directory of your project:
$ php -S localhost:8000 -t public/
Resources
Some resources for checking and study later. GraphQL is great combined with Lumen micro-framework.
I hope that this tutorial help someone in the future. If you have any questions, please comment!
Bye! :)