Laravel API Boilerplate is a "starter kit" you can use to build your first API in seconds. As you can easily imagine, it is built on top of the awesome Laravel Framework. This version is built on Laravel 5.6!
It is built on top of three big guys:
- JWT-Auth - tymondesigns/jwt-auth
- Dingo API - dingo/api
- Laravel-CORS - barryvdh/laravel-cors
- Eloquent File Field - jaysson/eloquent_filefield
- Laravel MySQL Spatial extension - grimzy/laravel-mysql-spatial
- Laravel API Documentation Generator - mpociot/laravel-apidoc-generator
- Associate users with permissions and roles - spatie/laravel-permission
- Eloquent-Sluggable - cviebrock/eloquent-sluggable
What I made is really simple: an integration of these three packages and a setup of some authentication and credentials recovery methods.
- run
composer create-project francescomalatesta/laravel-api-boilerplate-jwt myNextProject
; - have a coffee, nothing to do here;
Once the project creation procedure will be completed, run the php artisan migrate
command to install the required tables.
I wrote a couple of articles on this project that explain how to write an entire sample application with this boilerplate. They cover the older version of this boilerplate, but all the concepts are the same. You can find them on Sitepoint:
Just be aware that some options in the config/boilerplate.php
file are changed, so take a look to it.
WARNING: the articles are old and Laravel 5.1 related. Just use them as "inspiration". Even without updated tutorials, they should be enough.
You don't have to worry about authentication and password recovery anymore. I created four controllers you can find in the App\Api\V1\Controllers
for those operations.
For each controller there's an already setup route in routes/api.php
file:
POST api/auth/login
, to do the login and get your access token;POST api/auth/refresh
, to refresh an existent access token by getting a new one;POST api/auth/signup
, to create a new user into your application;POST api/auth/recovery
, to recover your credentials;POST api/auth/reset
, to reset your password after the recovery;POST api/auth/logout
, to log out the user by invalidating the passed token;GET api/auth/me
, to get current user data;
All the API routes can be found in the routes/api.php
file. This also follow the Laravel 5.5 convention.
Every time you create a new project starting from this repository, the php artisan jwt:generate command will be executed.
You can find all the boilerplate specific settings in the config/boilerplate.php
config file.
<?php
return [
// these options are related to the sign-up procedure
'sign_up' => [
// this option must be set to true if you want to release a token
// when your user successfully terminates the sign-in procedure
'release_token' => env('SIGN_UP_RELEASE_TOKEN', false),
// here you can specify some validation rules for your sign-in request
'validation_rules' => [
'name' => 'required',
'email' => 'required|email',
'password' => 'required'
]
],
// these options are related to the login procedure
'login' => [
// here you can specify some validation rules for your login request
'validation_rules' => [
'email' => 'required|email',
'password' => 'required'
]
],
// these options are related to the password recovery procedure
'forgot_password' => [
// here you can specify some validation rules for your password recovery procedure
'validation_rules' => [
'email' => 'required|email'
]
],
// these options are related to the password recovery procedure
'reset_password' => [
// this option must be set to true if you want to release a token
// when your user successfully terminates the password reset procedure
'release_token' => env('PASSWORD_RESET_RELEASE_TOKEN', false),
// here you can specify some validation rules for your password recovery procedure
'validation_rules' => [
'token' => 'required',
'email' => 'required|email',
'password' => 'required|confirmed'
]
]
];
As I already said before, this boilerplate is based on dingo/api and tymondesigns/jwt-auth packages. So, you can find many informations about configuration here and here.
However, there are some extra options that I placed in a config/boilerplate.php file:
sign_up.release_token
: set it totrue
if you want your app release the token right after the sign up process;reset_password.release_token
: set it totrue
if you want your app release the token right after the password reset process;
There are also the validation rules for every action (login, sign up, recovery and reset). Feel free to customize it for your needs.
You can create endpoints in the same way you could to with using the single dingo/api package. You can read its documentation for details. After all, that's just a boilerplate! :)
However, I added some example routes to the routes/api.php
file to give you immediately an idea.
If you want to enable CORS for a specific route or routes group, you just have to use the cors middleware on them.
Thanks to the barryvdh/laravel-cors package, you can handle CORS easily. Just check the docs at this page for more info.
If you want to contribute to this project, feel free to do it and open a PR. However, make sure you have tests for what you implement.
In order to run tests:
- create a
homestead_test
database on your machine; - run
vendor/bin/phpunit
;
If you want to specify a different name for the test database, don't forget to change the value in the phpunix.xml
file.
I currently made this project for personal purposes. I decided to share it here to help anyone with the same needs. If you have any feedback to improve it, feel free to make a suggestion, or open a PR!