README

ExA

Opinionated Modularized API Skeleton for Laravel

Features

Your API running on the latest version of Laravel and PHP
API Documentation with Swagger
Laravel Pint configuration (very opinionated)
Pest v3 for Tests
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
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

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

Configuring the Application

Copy the .env.example to .env and update the needed values

cp .env.example .env

Install the dependencies

composer install

Generate the application key and JWT secret

php artisan key:generate --ansi && php artisan jwt:secret

Run the migrations

php artisan migrate

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

php artisan db:seed

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

php artisan make:module 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

Run the linter (Pint) in the whole codebase

composer lint

Run the test suite

composer test

Update the Swagger docs

composer swagger

Run the linter (Pint) in staged files and update the Swagger docs

composer prepare

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 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.

wendelladriel / laravel-exa

Maintainers

Details