{"id":13620320,"url":"https://github.com/WendellAdriel/laravel-exa","last_synced_at":"2025-04-14T19:31:52.644Z","repository":{"id":65973756,"uuid":"602205799","full_name":"WendellAdriel/laravel-exa","owner":"WendellAdriel","description":"Opinionated Modularized API Skeleton for Laravel","archived":false,"fork":false,"pushed_at":"2025-03-12T18:35:26.000Z","size":2724,"stargazers_count":104,"open_issues_count":0,"forks_count":9,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-10T14:46:28.751Z","etag":null,"topics":["api","boilerplate","docker","laravel","skeleton","template"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WendellAdriel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["WendellAdriel"],"custom":["https://www.paypal.me/wendelladriel"]}},"created_at":"2023-02-15T18:07:56.000Z","updated_at":"2025-03-15T22:12:19.000Z","dependencies_parsed_at":"2024-04-26T15:43:10.082Z","dependency_job_id":"d664b63a-0b35-46bf-8f7f-870a76be616c","html_url":"https://github.com/WendellAdriel/laravel-exa","commit_stats":{"total_commits":32,"total_committers":1,"mean_commits":32.0,"dds":0.0,"last_synced_commit":"b460d3ed2af0a4acf359a9ba9d6876b6b6120b93"},"previous_names":[],"tags_count":18,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WendellAdriel%2Flaravel-exa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WendellAdriel%2Flaravel-exa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WendellAdriel%2Flaravel-exa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WendellAdriel%2Flaravel-exa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WendellAdriel","download_url":"https://codeload.github.com/WendellAdriel/laravel-exa/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248945961,"owners_count":21187420,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","boilerplate","docker","laravel","skeleton","template"],"created_at":"2024-08-01T21:00:54.445Z","updated_at":"2025-04-14T19:31:47.635Z","avatar_url":"https://github.com/WendellAdriel.png","language":"PHP","funding_links":["https://github.com/sponsors/WendellAdriel","https://www.paypal.me/wendelladriel"],"categories":["PHP","Starter Kits"],"sub_categories":["API"],"readme":"\u003cdiv align=\"center\"\u003e\n    \u003cp\u003e\n        \u003ch1\u003eExA\u003c/h1\u003e\n        Opinionated Modularized API Skeleton for Laravel\n    \u003c/p\u003e\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://packagist.org/packages/WendellAdriel/laravel-exa\"\u003e\u003cimg src=\"https://img.shields.io/packagist/v/WendellAdriel/laravel-exa.svg?style=flat-square\" alt=\"Packagist\"\u003e\u003c/a\u003e\n\u003ca href=\"https://packagist.org/packages/WendellAdriel/laravel-exa\"\u003e\u003cimg src=\"https://img.shields.io/packagist/php-v/WendellAdriel/laravel-exa.svg?style=flat-square\" alt=\"PHP from Packagist\"\u003e\u003c/a\u003e\n\u003ca href=\"https://packagist.org/packages/WendellAdriel/laravel-exa\"\u003e\u003cimg src=\"https://img.shields.io/badge/Laravel-11.x-brightgreen.svg?style=flat-square\" alt=\"Laravel Version\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"#features\"\u003eFeatures\u003c/a\u003e |\n    \u003ca href=\"#using-the-template\"\u003eUsage\u003c/a\u003e |\n    \u003ca href=\"#configuring-the-application\"\u003eConfiguration\u003c/a\u003e |\n    \u003ca href=\"#application-structure\"\u003eStructure\u003c/a\u003e |\n    \u003ca href=\"#exa-classes\"\u003eExA Classes\u003c/a\u003e |\n    \u003ca href=\"#credits\"\u003eCredits\u003c/a\u003e |\n    \u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e\n\u003c/p\u003e\n\n## Features\n\n* Your API running on the latest version of Laravel and PHP\n* Docker config with PHP, Nginx, MySQL, Redis and Mailpit\n* API Documentation with Swagger\n* Laravel Pint configuration (very opinionated)\n* Pest v2 for Tests\n* Type Coverage Tests with 100% type coverage\n* Base classes to speed up the development\n* DTOs with [Laravel Validated DTO](https://github.com/WendellAdriel/laravel-validated-dto)\n* Slack Client for notifications\n* API structured in modules\n* JWT for Authentication\n* Users management out-of-the-box with simple roles system\n* Logs on DB for user logins and for actions made on models\n* [Strictus](https://github.com/php-strictus/strictus) for enforcing local variable types\n* Models extending from BaseModel use soft deletes by default\n* Log actions made by users with the `created_by`, `updated_by` and `deleted_by` fields. Use the `$table-\u003euserActions()` in your migrations to add these fields.\n\n## Using the Template\n\nThere are three ways of using this template:\n\n### Composer (Recommended)\n\n```bash\ncomposer create-project --prefer-dist wendelladriel/laravel-exa my-app\n```\n\n### GitHub Template\n\nClick the `Use this template` button in the GitHub repository page.\n\n### Git Clone\n\n```bash\ngit clone git@github.com:WendellAdriel/laravel-exa.git my-app \u0026\u0026 cd my-app \u0026\u0026 rm -rf .git\n```\n\n## Configuring the Application\n\nBuild the docker services with\n\n```bash\nmake build\n```\n\nRun this command for the initial app configuration\n\n```bash\nmake configure\n```\n\n### Database Config\n\nStart the DB container with\n\n```bash\nmake db-start\n```\n\nRun the migrations\n\n```bash\nmake art ARGS=\"migrate\"\n```\n\nUpdate the admin user in the `database/seeders/DatabaseSeeder.php` file and run the seeds\n\n```bash\nmake art ARGS=\"db:seed\"\n```\n\nStop the DB container with\n\n```bash\nmake db-stop\n```\n\n### M1/2 Processor Config\n\nIf you're using a **Mac** with **M1/2 processor**, you need to update the `M1_PROCESSOR` env variable to `true`\n\n### XDebug Config\n\nBy default, **XDebug** will be installed, if you want to disable it, update the `XDEBUG_ENABLED` env variable to `false`\n\nYou can also configure **XDebug** by updating the `docker/app/config/xdebug.ini` file\n\n### Updating Services Ports\n\nYou can update which ports the services will connect to your machine by updating these variables in the `.env` file\n\n* `APP_EXTERNAL_PORT`\n* `APP_EXTERNAL_PORT_SSL`\n* `SWAGGER_EXTERNAL_PORT`\n* `DB_EXTERNAL_PORT`\n* `REDIS_EXTERNAL_PORT`\n* `MAILPIT_EXTERNAL_PORT_SMTP`\n* `MAILPIT_EXTERNAL_PORT_HTTP`\n\n## Running the Application\n\nRun this command to start the application\n\n```bash\nmake start\n```\n\nAfter completion, you can access the application at\n\n```bash\nhttp://localhost:APP_EXTERNAL_PORT\n```\n\nBy default, the `APP_EXTERNAL_PORT` is `8000`\n\n```bash\nhttp://localhost:8000\n```\n\nYou can check the Swagger docs at\n\n```bash\nhttp://localhost:SWAGGER_EXTERNAL_PORT\n```\n\nBy default, the `SWAGGER_EXTERNAL_PORT` is `8080`\n\n```bash\nhttp://localhost:8080\n```\n\n## Application Structure\n\nThe `app` folder contains only the files of a default **Laravel** installation.\n\nThe `exa` folder contains all the base classes provided by this **skeleton** to help you to develop your **API**.\n\nThe `modules` folder contains the code for your application. By default, you have an **Auth** module for **Authentication**,\nand **User management out-of-the-box**. It also provides a **Common** module that you can put shared logic for\nyour application.\n\n### Creating Modules\n\nTo create new modules you can use this command\n\n```bash\nmake art ARGS=\"make:module NAME\"\n```\n\nThis will create a new module inside the `modules` folder with the same structure of the other modules. It will create\nthe module disabled by default. To enable it, add the new module name to the `config/modules.php` file.\n\n### Commands Available\n\nFor running Pint in the whole codebase use\n\n```bash\nmake lint\n```\n\nFor running the test suite use\n\n```bash\nmake test\n```\n\nUse this command to see all the commands available\n\n```bash\nmake\n```\n\n## ExA Classes\n\nInside the `exa` folder, there are a lot of classes provided by this **skeleton** to help you to develop your **API**.\n\n### DTOs\n\n* `DatatableDTO` - This DTO provides basic filters for fetching data for datatables.\n* `DateRangeDTO` - This is an extension of the `DatatableDTO` providing additional parameters for date filters.\n\n### Exceptions\n\n- `ExaException` - Base class that all your custom exceptions should extend, so it can be handled properly by the `app/Exceptions/Handler`.\n- `AccessDeniedException` - Exception used for actions that the user is not allowed to perform.\n\n### Http\n\n#### Middlewares\n\n* `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.\n* `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.\n\n#### Responses\n\n* `ApiErrorResponse` - The class to be used to return any error responses, configured to be used by the `app/Exceptions/Handler`.\n* `ApiSuccessResponse` - The class to be used to return any success responses, configured to be used with **JSON Resources**.\n* `NoContentResponse` - The class to be used to return empty responses.\n\n### Models\n\n* `BaseModel` - Base class that all your models should extend, already configured with the `CommonQueries`, `LogChanges`, `SoftDeletes` and `UserActions` Traits.\n* `ChangeLog` - Model for the table that logs all changes made on other models.\n* `CommonQueries` - This Trait provides a lot of methods for common queries that you can use with your models.\n* `HasUuidField` - This Trait provides UUID field support for models that don't want the UUID to be the primary key.\n* `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.\n* `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.\n\n### Services\n\n* `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.\n\n### Support\n\n* `Datatable` - Class that provides functions for paginating, sorting and filtering data.\n* `Formatter` - Class that provides common values in constants and methods to format data in your application.\n* `ChangeAction` - Enum used by the `LogChanges` Trait.\n* `SortOption` - Enum for the sort order used by the `DatatableDTO`.\n\n## Credits\n\n- [Wendell Adriel](https://github.com/WendellAdriel)\n- [All Contributors](../../contributors)\n\n## Contributing\n\nCheck the **[Contributing Guide](CONTRIBUTING.md)**.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWendellAdriel%2Flaravel-exa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FWendellAdriel%2Flaravel-exa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWendellAdriel%2Flaravel-exa/lists"}