Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/WendellAdriel/laravel-exa

Opinionated Modularized API Skeleton for Laravel
https://github.com/WendellAdriel/laravel-exa

api boilerplate docker laravel skeleton template

Last synced: 12 days ago
JSON representation

Opinionated Modularized API Skeleton for Laravel

Lists

README 

        


    


        


ExA


        Opinionated Modularized API Skeleton for Laravel

    






Packagist

PHP from Packagist

Laravel Version






    Features |

    Usage |

    Configuration |

    Structure |

    ExA Classes |

    Credits |

    Contributing




## 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](https://github.com/WendellAdriel/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](https://github.com/php-strictus/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)



```bash

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



```bash

git clone [email protected]:WendellAdriel/laravel-exa.git my-app && cd my-app && rm -rf .git

```



## Configuring the Application



Build the docker services with



```bash

make build

```



Run this command for the initial app configuration



```bash

make configure

```



### Database Config



Start the DB container with



```bash

make db-start

```



Run the migrations



```bash

make art ARGS="migrate"

```



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



```bash

make art ARGS="db:seed"

```



Stop the DB container with



```bash

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



```bash

make start

```



After completion, you can access the application at



```bash

http://localhost:APP_EXTERNAL_PORT

```



By default, the `APP_EXTERNAL_PORT` is `8000`



```bash

http://localhost:8000

```



You can check the Swagger docs at



```bash

http://localhost:SWAGGER_EXTERNAL_PORT

```



By default, the `SWAGGER_EXTERNAL_PORT` is `8080`



```bash

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



```bash

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



```bash

make lint

```



For running the test suite use



```bash

make test

```



Use this command to see all the commands available



```bash

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



- [Wendell Adriel](https://github.com/WendellAdriel)

- [All Contributors](../../contributors)



## Contributing



Check the **[Contributing Guide](CONTRIBUTING.md)**.