rygilles/laravel-api-boilerplate

Laravel API Boilerplate project.


README

StyleCI Build Status

This is a Laravel Laravel 5.* based project.

Prerequisites

Setup

Run this command and make sure to chmod properly the storage and cache folders.

composer create-project --prefer-dist rygilles/laravel-api-boilerplate your-project-name

Or install this project manually by cloning with git. In this case, you must copy the .env.example file to .env and run this command :

php artisan key:generate

.env file

Check the .env file and change the values according to you preferences.

Libs

This project uses the same libraries as Laravel common projects.

But also (Check composer.json and package.json file for details) :

Production environment

PHP, with composer

Back-office, Node.js dependencies

  • laravel-echo : Laravel Echo is a JavaScript library that makes it painless to subscribe to channels and listen for events broadcast by Laravel.
  • socket.io-client : Realtime application framework (client) used with Laravel Echo.

Development environment

  • nikic/php-parser : PHP parsing (Used with the php artisan app:makeApiModelResource command).
  • twig/twig : Twig template rendering (Used with the php artisan app:makeApiModelResource command).
  • barryvdh/laravel-ide-helper package : Tool for generating Laravel definitions (PhpDoc) php file. Adding auto-complete in your IDE.

Back-office, Node.js dependencies

Vue.js :

  • vue : Vue.js javascript framework for back-office UI.
  • vuex : Centralized state management for Vue.js.
  • vue-router : Official router for Vue.js.
  • vue-i18n : Translations management in Vue.js.
  • vue-gravatar : A dead-simple gravatar component for Vue.js.

Graphics :

Laravel :

  • laravel-mix : An elegant wrapper around Webpack for the 80% use case.
  • cross-env : Cross platform setting of environment scripts.

Miscellaneous :

  • jquery : Used with AdminLTE.
  • axios : Authentication and Api requesting.
  • pace : Dynamic loading bar (Top of the screen).
  • lodash : JavaScript utility library used with Vue.js.
  • moment : Dates formatter.

Database

This application use InnoDB tables for foreign keys constraint support and utf8mb4_unicode_ci encoding for modern chars support (including emoji). It also use UUID (128 bits).

Initialize

Run this command to create the database basics with default migrations (check database/migrations directory).

Make sure Redis is installed properly.

php artisan app:makeFresh

This will install :

Laravel basic tables : user, password_resets, notification, jobs

Passport bundle tables : oauth_auth_codes, oauth_access_tokens, oauth_refresh_tokens, oauth_clients_table, oauth_personal_access_clients)

Boilerplate tables : i18n_lang, user_group

Samples Data

An Artisan command (See below) can supply your database with samples data for users, projects, etc, for testing and documentation generation purpose.

Check database/seeds/Samples folder for more information.

User ID User Group ID Name Email Password
41abdec2-1389-11e7-93ae-92361f002671 Developer John Doe john.doe@domain.tld johndoe
509dd5c0-1389-11e7-93ae-92361f002671 Support Alan Smithee alan.smithee@domain.tld alansmithee
605c7610-1389-11e7-93ae-92361f002671 End-User John Smith john.smith@domain.tld johnsmith
82b5da82-138c-11e7-93ae-92361f002671 End-User Mickey Mouse mickey.mouse@domain.tld mickeymouse

Node, Laravel Mix and Laravel Echo Server

NodeJs

Install NodeJs dependencies (check package.json file for more information).

npm install

Laravel Mix

Assets

Create your own back-office images by replacing :

Check the webpack.mix.js to enable favicon.jpg copy and manage you own assets.

Compilation

Run this command to compile the assets

npm run dev

Laravel Echo Server

Real-time notifications and events are send by a local Node.js server, using Redis and Socket.io.

The whole process is handled by laravel-echo-server.

Initialize Laravel Echo Server by creating laravel-echo-server.json configuration file with this command :

laravel-echo-server init

Start and Auto-restart

Use PM2 for auto-restart feature

Make sure you've configured all in laravel-echo-server.ecosystem.config.json file. :

pm2 start laravel-echo-server.ecosystem.config.json

Or use this command to manually start the server :

laravel-echo-server start

Artisan commands

app:makeFresh

php artisan app:makeFresh

This command will reset/refresh migrations, re-create required database data and (optionally) create a fresh app with samples data.

app:generateApiDocs

php artisan app:generateApiDocs

Generate API documentation using current database resources.

Make sure you've configured all in config/apidocs.php file.

app:makeApiModelResource

php artisan app:makeApiModelResource

Only in development environment !

Generate and MODIFY source files to add a new model with related files :

During this command execution, the Laravel application will be down (php artisan down then php artisan up at the end, called implicitly).

Composer dump autoloads will be called at the end.

app:makeApiModelResourceAssets

php artisan app:makeApiModelResourceAssets

Only in development environment !

Generate and MODIFY basic assets source files for a new resource model in the dashboard :

During this command execution, the Laravel application will be down (php artisan down then php artisan up at the end, called implicitly).

Make sure to run npm run dev or npm run watch to check your assets compilation.

(Upcoming upgrades to do : Model resource analysis to complete new components fields and other stuff like this.)

openApiSchemas:generate

php artisan openApiSchemas:generate

This command is provided by the rygilles/laravel-openapi-schema-generator package.

It will analyze your laravel project files and generate a openapi json file, describing the capabilities of your Api.

Check the config/openapischemas.php configuration file before running this command.

Some information can not be retrieve automatically by the script, you might update/add data in the "openapi_bindings" configuration array.

ide-helper:generate

php artisan ide-helper:generate

This command is provided by barryvdh/laravel-ide-helper package.

Only for development environment

This package generates a file that your IDE understands, so it can provide accurate autocompletion. Generation is done based on the files in your project, so they are always up-to-date. If you don't want to generate it, you can add a pre-generated file to the root folder of your Laravel project (but this isn't as up-to-date as self generated files).