ExA

Opinionated Modularized API Skeleton for Laravel

Features

Your API running on the latest version of Laravel and PHP
Docker config with PHP, Nginx, MySQL, Redis and Mailpit
API Documentation with Swagger
Laravel Pint configuration (very opinionated)
Pest v2 for Tests
Type Coverage Tests with 100% type coverage
Base classes to speed up the development
DTOs with Laravel Validated DTO
Slack Client for notifications
API structured in modules
JWT for Authentication
Users management out-of-the-box with simple roles system
Logs on DB for user logins and for actions made on models
Strictus for enforcing local variable types
Models extending from BaseModel use soft deletes by default
Log actions made by users with the created_by, updated_by and deleted_by fields. Use the $table->userActions() in your migrations to add these fields.

Using the Template

There are three ways of using this template:

Composer (Recommended)

composer create-project --prefer-dist wendelladriel/laravel-exa my-app

GitHub Template

Click the Use this template button in the GitHub repository page.

Git Clone

git clone git@github.com:WendellAdriel/laravel-exa.git my-app && cd my-app && rm -rf .git

Configuring the Application

Build the docker services with

make build

Run this command for the initial app configuration

make configure

Database Config

Start the DB container with

make db-start

Run the migrations

make art ARGS="migrate"

Update the admin user in the database/seeders/DatabaseSeeder.php file and run the seeds

make art ARGS="db:seed"

Stop the DB container with

make db-stop

M1/2 Processor Config

If you're using a Mac with M1/2 processor, you need to update the M1_PROCESSOR env variable to true

XDebug Config

By default, XDebug will be installed, if you want to disable it, update the XDEBUG_ENABLED env variable to false

You can also configure XDebug by updating the docker/app/config/xdebug.ini file

Updating Services Ports

You can update which ports the services will connect to your machine by updating these variables in the .env file

APP_EXTERNAL_PORT
APP_EXTERNAL_PORT_SSL
SWAGGER_EXTERNAL_PORT
DB_EXTERNAL_PORT
REDIS_EXTERNAL_PORT
MAILPIT_EXTERNAL_PORT_SMTP
MAILPIT_EXTERNAL_PORT_HTTP

Running the Application

Run this command to start the application

make start

After completion, you can access the application at

http://localhost:APP_EXTERNAL_PORT

By default, the APP_EXTERNAL_PORT is 8000

http://localhost:8000

You can check the Swagger docs at

http://localhost:SWAGGER_EXTERNAL_PORT

By default, the SWAGGER_EXTERNAL_PORT is 8080

http://localhost:8080

Application Structure

The app folder contains only the files of a default Laravel installation.

The exa folder contains all the base classes provided by this skeleton to help you to develop your API.

The modules folder contains the code for your application. By default, you have an Auth module for Authentication, and User management out-of-the-box. It also provides a Common module that you can put shared logic for your application.

Creating Modules

To create new modules you can use this command

make art ARGS="make:module NAME"

This will create a new module inside the modules folder with the same structure of the other modules. It will create the module disabled by default. To enable it, add the new module name to the config/modules.php file.

Commands Available

For running Pint in the whole codebase use

make lint

For running the test suite use

make test

Use this command to see all the commands available

make

ExA Classes

Inside the exa folder, there are a lot of classes provided by this skeleton to help you to develop your API.

DTOs

DatatableDTO - This DTO provides basic filters for fetching data for datatables.
DateRangeDTO - This is an extension of the DatatableDTO providing additional parameters for date filters.

Exceptions

ExaException - Base class that all your custom exceptions should extend, so it can be handled properly by the app/Exceptions/Handler.
AccessDeniedException - Exception used for actions that the user is not allowed to perform.

Http

Middlewares

BlockViewerUsers - This middleware is a middleware applied to all routes that blocks any users with the role VIEWER to access any routes that are not GET routes.
HasRole - This middleware can be applied to routes that can be accessed only by users with a specific role or ADMINS that have full access.

Responses

ApiErrorResponse - The class to be used to return any error responses, configured to be used by the app/Exceptions/Handler.
ApiSuccessResponse - The class to be used to return any success responses, configured to be used with JSON Resources.
NoContentResponse - The class to be used to return empty responses.

Models

BaseModel - Base class that all your models should extend, already configured with the CommonQueries, LogChanges, SoftDeletes and UserActions Traits.
ChangeLog - Model for the table that logs all changes made on other models.
CommonQueries - This Trait provides a lot of methods for common queries that you can use with your models.
HasUuidField - This Trait provides UUID field support for models that don't want the UUID to be the primary key.
LogChanges - This Trait provides listeners for logging changes on the models. Check the class to know how you can customize your models with the properties of this Trait.
UserActions - This Trait provides listeners for logging changes made by users on the models populating the created_by, updated_by and deleted_by fields. Check the class to know how you can customize your models with the properties of this Trait.

Services

SlackClient - Class to send notifications to Slack. You need to add the needed configuration in your env, check the config/services.php file for the slack service to know how to configure it.

Support

Datatable - Class that provides functions for paginating, sorting and filtering data.
Formatter - Class that provides common values in constants and methods to format data in your application.
ChangeAction - Enum used by the LogChanges Trait.
SortOption - Enum for the sort order used by the DatatableDTO.

Credits

Contributing

Check the Contributing Guide.