rygilles/laravel-api-boilerplate

Laravel API Boilerplate project.

Laravel API Boilerplate

, _(*1)

This is a Laravel Laravel 5.* based project., _(*2)

Prerequisites

• PHP 7.*+ (for Laravel 5.5+ framework)
• Node.js 6.*+
• Redis 3+
• Laravel Echo Server 1.3.*+ installed globally
• PM 2 (Optional : Run Laravel Echo Server as a "daemon")

Setup

Run this command and make sure to chmod properly the storage and cache folders., _(*3)

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 :, _(*4)

php artisan key:generate

.env file

Check the .env file and change the values according to you preferences., _(*5)

Libs

This project uses the same libraries as Laravel common projects., _(*6)

But also (Check composer.json and package.json file for details) :, _(*7)

Production environment

PHP, with composer

• alsofronie/eloquent-uuid for User, UserGroup and Notification models.
• bugsnag/bugsnag-laravel for debug purpose (Set BUGSNAG_API_KEY in your .env file).
• dingo/api for Api features.
• felixkiss/uniquewith-validator for advanced validation rule.
• filp/whoops for better error display in debug mode.
• predis/predis for interactions with redis server and laravel-echo-server.
• rygilles/laravel-apidoc-generator for generating Api documentation.
• rygilles/laravel-openapi-schema-generator for generating Open API json file.

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 :, _(*8)

• 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 :, _(*9)

• admin-lte : Back-office dashboard and control panel.
• bootstrap-less and bootstrap-sass : Used with AdminLTE.
• node-sass : Used with AdminLTE.
• font-awesome : Used with AdminLTE.
• ionicons : Used with AdminLTE.
• noty : Live notifications UI.
• datatables.net-select-dt : Used for custom data table component styles.

Laravel :, _(*10)

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

Miscellaneous :, _(*11)

• 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)., _(*12)

Initialize

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

Make sure Redis is installed properly., _(*14)

php artisan app:makeFresh

This will install :, _(*15)

Laravel basic tables : user, password_resets, notification, jobs, _(*16)

Passport bundle tables : oauth_auth_codes, oauth_access_tokens, oauth_refresh_tokens, oauth_clients_table, oauth_personal_access_clients), _(*17)

Boilerplate tables : i18n_lang, user_group, _(*18)

Samples Data

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

Check database/seeds/Samples folder for more information., _(*20)

Node, Laravel Mix and Laravel Echo Server

NodeJs

Install NodeJs dependencies (check package.json file for more information)., _(*21)

npm install

Laravel Mix

Assets

Create your own back-office images by replacing :, _(*22)

• resources/assets/img/dashboard-logo.png (50 x 200)
• resources/assets/img/dashboard-mini-logo.png (50 x 50)
• resources/assets/img/favicon.jpg

Check the webpack.mix.js to enable favicon.jpg copy and manage you own assets., _(*23)

Compilation

Run this command to compile the assets, _(*24)

npm run dev

Laravel Echo Server

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

The whole process is handled by laravel-echo-server., _(*26)

Initialize Laravel Echo Server by creating laravel-echo-server.json configuration file with this command :, _(*27)

laravel-echo-server init

Start and Auto-restart

Use PM2 for auto-restart feature, _(*28)

Make sure you've configured all in laravel-echo-server.ecosystem.config.json file. :, _(*29)

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

Or use this command to manually start the server :, _(*30)

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., _(*31)

app:generateApiDocs

php artisan app:generateApiDocs

Generate API documentation using current database resources., _(*32)

Make sure you've configured all in config/apidocs.php file., _(*33)

app:makeApiModelResource

php artisan app:makeApiModelResource

Only in development environment !, _(*34)

Generate and MODIFY source files to add a new model with related files :, _(*35)

• Model : Created in app/Models folder.
• Migration (Optional) : Created in database/migrations folder.
• Init seeder (Optional) : Created in database/seeds folder. That will also MODIFY the database/seeds/InitSeeder.php file !
• Samples seeder (Optional) : Created in database/seeds/Samples folder. That will also MODIFY the database/seeds/Samples/SamplesSeeder.php file !
• Controller (Optional) : Created in app/Http/Controllers/Api folder. That will also MODIFY the routes/api.php file !
• Requests : Will be generated if "store" method or "update" method making is wanted. In app/Http/Requests folder.
• Transformer : Will be generated if needed. In app/Http/Transformers/Api folder.

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

Composer dump autoloads will be called at the end., _(*37)

app:makeApiModelResourceAssets

php artisan app:makeApiModelResourceAssets

Only in development environment !, _(*38)

Generate and MODIFY basic assets source files for a new resource model in the dashboard :, _(*39)

• Resource model list vue component : Created in resources/assets/js/components/dashboard folder.
• Resource model item vue component : Created in resources/assets/js/components/dashboard folder.
• Resource model locales js files : Created in resources/assets/js/locales folder (one file per locale).
• Routes locales js files resources/assets/js/locales/en/routes.js and other locales file : MODIFY to add resource model list and item routes.
• Vuex store js file resources/assets/js/store.js : MODIFY to add resource model state, getters, mutations and actions.
• Routes js file resources/assets/js/routes.js : MODIFY to add resource model list and item routes.
• Side-bar menu vue component file resources/assets/js/components/includes/sidebar-menu.vue : MODIFY to add resource model links (interactive).

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

Make sure to run npm run dev or npm run watch to check your assets compilation., _(*41)

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

openApiSchemas:generate

php artisan openApiSchemas:generate

This command is provided by the rygilles/laravel-openapi-schema-generator package., _(*43)

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

Check the config/openapischemas.php configuration file before running this command., _(*45)

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

ide-helper:generate

php artisan ide-helper:generate

This command is provided by barryvdh/laravel-ide-helper package., _(*47)

Only for development environment, _(*48)

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)., _(*49)