plin-code / laravel-clean-architecture
Laravel package for generating Clean Architecture structure
Package info
github.com/plin-code/laravel-clean-architecture
pkg:composer/plin-code/laravel-clean-architecture
Requires
- php: ^8.3
- illuminate/console: ^12.0 || ^13.0
- illuminate/filesystem: ^12.0 || ^13.0
- illuminate/support: ^12.0 || ^13.0
Requires (Dev)
- larastan/larastan: ^3.9
- laravel/pint: ^1.13
- mockery/mockery: ^1.6
- orchestra/testbench: ^10.0 || ^11.0
- pestphp/pest: ^3.0 || ^4.0
- pestphp/pest-plugin-laravel: ^3.0 || ^4.0
- phparkitect/phparkitect: ^1.3
- symfony/process: ^7.0 || ^8.0
Suggests
- laravel/boost: 2.5 or higher reads the AI guidelines and agent skill shipped in resources/boost
- phparkitect/phparkitect: Required to run the rules generated by clean-arch:make-arch-rules
Provides
None
Conflicts
None
Replaces
None
README
Laravel Clean Architecture
A Laravel package to easily implement Clean Architecture in your projects.
โจ Features
- ๐ฏ Domain-Driven Design - Organize your code with DDD principles
- โก Quick Setup - Get started with Clean Architecture in minutes
- ๐งฉ Auto-Generation - Generate complete domains with one command
- ๐๏ธ Layer Separation - Clear separation between Domain, Application, and Infrastructure
- ๐ง Customizable - Flexible configuration to fit your project needs
- ๐งช Test-Ready - Pre-built test templates for immediate testing
- ๐ Well-Documented - Comprehensive documentation and examples
- ๐จ Modern PHP - Built for PHP 8.3+ with latest Laravel features
๐ Requirements
- ๐ PHP 8.3+
- โก Laravel 12.x / 13.x
๐ฆ Installation
composer require plin-code/laravel-clean-architecture
โ๏ธ Configuration
Publish the configuration files and stubs:
php artisan vendor:publish --provider="PlinCode\LaravelCleanArchitecture\CleanArchitectureServiceProvider"
๐ฏ Usage
๐๏ธ Installing Clean Architecture structure
php artisan clean-arch:install
This command will create:
- ๐ Folder structure for Domain, Application and Infrastructure layers
- ๐งฉ Base classes (BaseModel, BaseAction, BaseService, etc.)
- โ๏ธ Configuration file
- ๐ Documentation
๐ค Moving the User model into the Domain
php artisan clean-arch:install --user-in-domain composer dump-autoload
Laravel keeps User in app/Models, outside the directories the generated phparkitect rules check. This option moves it into the Domain layer of a fresh app, following directories.domain and generation.model_directory, so with the defaults you get app/Domain/Users/Models/User.php declaring App\Domain\Users\Models\User.
It also:
- keeps
UseranAuthenticatable, it does not extendBaseModel(whoseSoftDeletesneeds adeleted_atcolumn theuserstable does not have) - adds
newFactory()to the model and a$modelproperty todatabase/factories/UserFactory.php, since the factory resolver derives both names from the old namespace - rewrites
App\Models\Userin the PHP files ofapp/,config/,database/,routes/andtests/, in code and inside strings, and prints every file it changed - registers
Relation::morphMap(['user' => User::class])inAppServiceProvider::boot(), so polymorphic*_typecolumns storeuserinstead of a namespace - renames the
App.Models.User.{id}broadcast channel inroutes/channels.php - removes
app/Modelsandapp/Httponce they hold nothing but the default empty base controller
It does not touch vendor/, node_modules/ or storage/, and it does not migrate data. If resources/js or resources/ts listens on App.Models.User.{id}, the command warns and names the files. Those Echo listeners have to be renamed by hand.
The command refuses to change anything when app/Models holds other models (pass --force to move User anyway) or when both the source and the destination exist. For an app that is already running in production, read Moving User into the Domain in an existing app first.
Laravel's own generators (make:model, make:controller, make:request) recreate app/Models and app/Http. After this option, use the clean-arch:make-* commands instead.
๐ Migrating an existing app into the layers
php artisan clean-arch:install --migrate-app composer dump-autoload
Without options, clean-arch:install creates the layers next to the folders Laravel ships with and leaves those folders alone, so an app ends up with both app/Http/Controllers and app/Infrastructure/Http/Controllers. --migrate-app moves the code of those folders into the layers, rewrites the namespaces and every reference, and prints each file it moved, changed or removed. It works on a fresh app, on an app created from a starter kit (the React, Vue and Livewire kits ship folders such as app/Http/Controllers/Settings, app/Http/Middleware, app/Http/Requests/Settings, app/Actions/Fortify and app/Concerns), and on an app where some of these folders do not exist, which are skipped.
| From | To |
|---|---|
app/Http/Controllers |
Infrastructure/Http/Controllers |
app/Http/Middleware |
Infrastructure/Http/Middleware |
app/Http/Requests |
Infrastructure/Http/Requests |
app/Http/Resources |
Infrastructure/Http/Resources |
app/Console/Commands |
Infrastructure/Console/Commands |
app/Mail, app/Notifications, app/Observers, app/Exports |
Infrastructure/Mail, Infrastructure/Notifications, Infrastructure/Observers, Infrastructure/Exports |
app/Actions, app/Services, app/Jobs, app/Listeners, app/Concerns |
Application/Actions, Application/Services, Application/Jobs, Application/Listeners, Application/Concerns |
app/Models/User.php |
Domain/Users/Models/User.php, as with --user-in-domain, when User is the only model |
The destinations follow directories, so with app/Core/Infrastructure the controllers land in app/Core/Infrastructure/Http/Controllers. Subfolders are kept: app/Http/Controllers/Settings/ProfileController.php becomes app/Infrastructure/Http/Controllers/Settings/ProfileController.php declaring App\Infrastructure\Http\Controllers\Settings.
It also:
- deletes the empty abstract
ControllerLaravel ships, so its subclasses extend the base controllerclean-arch:installwrites and the app keeps a single base controller - rewrites the old namespaces in the PHP files of
app/,bootstrap/(withoutbootstrap/cache),config/,database/,routes/andtests/, in code, inside strings and in fully qualified names - adds
->withCommands([...])for moved console commands and->withEvents(discover: [...])for moved listeners tobootstrap/app.php, since Laravel only discovers them inapp/Console/Commandsandapp/Listeners. Whenbootstrap/app.phphas noreturn Application::configure(...)line, or already callswithEvents()(a second call would replace its discovery paths), it prints the exact lines to add instead - rewrites Wayfinder imports in
resources/jsandresources/ts,@/actions/App/Http/Controllers/...becoming@/actions/App/Infrastructure/Http/Controllers/.... The generatedactions,routesandwayfinderfolders are left to Wayfinder: runphp artisan wayfinder:generate --with-form(or the next Vite build) to regenerate them - removes the folders it emptied, then lists every PHP file still outside the layers
What stays where it is, and why:
app/Providers:bootstrap/providers.phpregisters the providers there, andvalidation.outside_layers_allowedallows it by default.app/Modelswhen it holds other models besidesUser: models of one namespace name each other without imports, factories and policies are found from the model namespace, and polymorphic columns store the class name. Moving them is a decision per model, so all of them stay,Userincluded, and the command says so. Move them by hand (the layoutclean-arch:make-domaingenerates is a reference), or moveUseralone with--user-in-domain --force.app/Policies: policy auto discovery looks inApp\Policies. Keep it, and add'Policies'tovalidation.outside_layers_allowed.- Every other folder, such as
app/Events,app/Enums,app/Rules,app/Livewire,app/Vieworapp/Filament: Livewire, Blade components and Filament find their classes by namespace or by path, so these folders are listed and left for you to decide.
Before moving anything the command checks every destination. When one already exists, including the base classes clean-arch:install writes (Http/Controllers/Controller.php, Http/Requests/BaseRequest.php, Actions/BaseAction.php, Services/BaseService.php), it prints every conflict and exits 1 without changing a file. A base controller with code of its own is such a conflict. --force replaces the destination with the file of the app, and, as always with --force, also overwrites the files clean-arch:install generates. vendor/, node_modules/ and storage/ are never touched.
What it does not do:
- It does not rewrite paths written as strings, such as
app_path('Http/Controllers')or__DIR__.'/../app/Console/Commands', nor files that are not PHP outside the Wayfinder imports (Blade views,phpunit.xml,phpstan.neon). - It does not sort the
usestatements it rewrites. Run your formatter afterwards. - It does not migrate data. A job or a listener already serialized in the queue names its old class, so drain the queue before deploying, as for moving
User. - It does not run
composer dump-autoload, Wayfinder or your tests. Run them, then turn onno_classes_outside_layersto keep the app inside the layers.
๐ Creating a new domain
php artisan clean-arch:make-domain User
This command will generate:
- ๐๏ธ Domain model with events
- ๐ Status enums
- ๐ Domain events (Created, Updated, Deleted)
- โก Actions (Create, Update, Delete, GetById, List)
- ๐ API Controller
- ๐ Form Requests (Create, Update)
- ๐ค API Resource
- ๐๏ธ Database migration
- ๐ญ Model factory in
database/factories, which the model names innewFactory() - ๐งช Feature tests
After generating the core files, make-domain prompts interactively for optional components. You can choose to also generate an Observer, Listener, Job, Mail, Notification, and Export for the domain. Each prompt can be answered independently, so you only generate what your domain needs.
make-domain does not touch your routes. When it finishes it prints the Route::apiResource() line for the generated controller, which the generated feature test calls under /api. Add it to routes/api.php. A fresh Laravel app has no such file: php artisan install:api creates it and registers it in bootstrap/app.php, and it also installs Sanctum.
โ Architecture validation
Architectural rules are enforced by phparkitect. The package does not depend on it and does not run it: it generates a configuration file from config/clean-architecture.php, and your project runs the tool.
composer require --dev phparkitect/phparkitect php artisan clean-arch:make-arch-rules vendor/bin/phparkitect check
clean-arch:make-arch-rules writes phparkitect.php in the project root, built from directories, default_namespace and validation.rules. It refuses to overwrite an existing file, so pass --force when you want to regenerate one. The generated file is ordinary PHP: once you need rules the package does not generate, edit it by hand and stop regenerating it.
phparkitect check exits 1 when it finds violations, which is what you want in CI. Rules can be disabled one by one, see Validation rules.
Delegating brings something the previous hand written analyser could not do: inheritance chains are followed. A console command extending a project specific base class that itself extends Illuminate\Console\Command is now reported, and so is a job extending an abstract base job that implements ShouldQueue.
๐ก๏ธ The autoload guard
The generated file opens with a check that looks out of place until it saves you:
use App\Domain\Shared\BaseModel; use Illuminate\Console\Command; if (! class_exists(Command::class) || ! class_exists(BaseModel::class)) { throw new RuntimeException( 'clean-architecture: autoloading does not resolve the application classes, ' .'so the reflection based rules would pass silently. Run composer dump-autoload.' ); }
Two of the rules are reflection based. When autoloading does not resolve the classes being scanned, is_a() reads an unloadable class as "not a subclass", so those rules report nothing and phparkitect exits 0. In CI that is indistinguishable from a clean run. The guard turns that case into a failure with a message, and it costs nothing because it runs before the scan.
The BaseModel it imports is the one clean-arch:install generates for your domain layer. If you rename or remove it, the guard fires even with a sound autoloader. That is a false alarm, and it is the right way round to be wrong: a false alarm is loud and the message says what to look at, a silent pass is neither. Point the import at another class of yours and keep it.
๐ Adopting it on an existing codebase
A codebase that has never been checked usually starts with a long list of violations. Record them once and fail only on new ones:
vendor/bin/phparkitect generate-baseline vendor/bin/phparkitect check
generate-baseline writes phparkitect-baseline.json with the violations found today, and check picks that file up automatically and exits 0. Regenerate it as you fix things, or pass --skip-baseline to see the full list again. Fixing the recorded violations does not require regenerating: the baseline is a list of what to ignore, not a target.
๐ ๏ธ Available commands
clean-arch:install {--force} {--user-in-domain} {--migrate-app}: ๐๏ธ Install Clean Architecture structure, optionally moving theUsermodel into the Domain layer, or the code of the Laravel folders into the layersclean-arch:make-domain {name} {--force} {--no-base}: ๐ Create a complete new domainclean-arch:make-action {name} {domain} {--force} {--no-base}: โก Create a new actionclean-arch:make-service {name} {--force} {--no-base}: ๐ง Create an empty service, for logic shared by several actionsclean-arch:make-controller {name} {--api} {--web} {--force}: ๐ Create a new controllerclean-arch:make-observer {name} {domain} {--force}: ๐๏ธ Create a new observerclean-arch:make-listener {name} {--force}: ๐ Create a new listenerclean-arch:make-job {name} {--force}: โณ Create a new jobclean-arch:make-mail {name} {--force}: ๐ง Create a new mailableclean-arch:make-notification {name} {--force}: ๐ Create a new notificationclean-arch:make-export {name} {--force}: ๐ค Create a new exportclean-arch:make-arch-rules {--force}: ๐ก๏ธ Generate a phparkitect config from the configured rulesclean-arch:generate-package {name} {vendor} {--force}: ๐ฆ Generate a new package
๐ Project structure after clean-arch:install
app/
โโโ Domain/ # Business logic (Eloquent models, enums, events)
โโโ Application/ # Use cases and orchestration
โ โโโ Actions/
โ โโโ Services/
โ โโโ Jobs/
โ โโโ Listeners/
โโโ Infrastructure/ # Framework adapters
โโโ Http/
โ โโโ Controllers/
โ โ โโโ Api/
โ โ โโโ Web/
โ โโโ Middleware/
โ โโโ Requests/
โ โโโ Resources/
โโโ Mail/
โโโ Notifications/
โโโ Observers/
โโโ Exports/
โโโ Validation/
โโโ Console/Commands/
โโโ Exceptions/
Laravel only auto-discovers commands in app/Console/Commands, so register the commands of the Infrastructure layer in bootstrap/app.php (adjust the path if you changed directories.infrastructure):
->withCommands([ __DIR__.'/../app/Infrastructure/Console/Commands', ])
๐ Generated structure after clean-arch:make-domain User
The model sits in a Models subfolder by default. Set generation.model_directory to change or drop it, see Model directory.
app/
โโโ Domain/
โ โโโ Users/
โ โโโ Models/
โ โ โโโ User.php
โ โโโ Enums/
โ โ โโโ UserStatus.php
โ โโโ Events/
โ โโโ UserCreated.php
โ โโโ UserUpdated.php
โ โโโ UserDeleted.php
โโโ Application/
โ โโโ Actions/
โ โ โโโ Users/
โ โ โโโ CreateUserAction.php
โ โ โโโ UpdateUserAction.php
โ โ โโโ DeleteUserAction.php
โ โ โโโ GetByIdUserAction.php
โ โ โโโ ListUsersAction.php
โโโ Infrastructure/
โโโ Http/
โโโ Controllers/
โ โโโ Api/
โ โโโ UsersController.php
โโโ Requests/
โ โโโ CreateUserRequest.php
โ โโโ UpdateUserRequest.php
โโโ Resources/
โโโ UserResource.php
๐๏ธ Clean Architecture Principles
This package implements Clean Architecture principles:
- ๐ฏ Domain Layer: Contains business logic and entities
- โก Application Layer: Contains use cases and application logic
- ๐๏ธ Infrastructure Layer: Contains implementation details (controllers, database, etc.)
๐ Dependencies
- ๐ฏ Domain Layer: Does not depend on the Application or Infrastructure layers
- โก Application Layer: Depends only on Domain Layer
- ๐๏ธ Infrastructure Layer: Depends on Application and Domain Layers
๐ Crossing a layer with a contract
When an inner layer needs something an outer layer provides, it declares an interface and the outer layer implements it. The binding lives in a service provider, so the inner layer only ever sees the interface.
- External service: the interface sits in
App\Application\Contracts(for examplePaymentGateway), the adapter inApp\Infrastructure(StripePaymentGateway). Switching provider means a new adapter and a new binding. - Domain asking the outside: the domain needs an answer it does not own, such as a feature flag. The interface sits in the domain (
App\Domain\Orders\Contracts\DiscountsGate), the implementation inApp\Application. - Shared capability: several models implement the same interface (
HasSlug), so one service handles all of them.
// AppServiceProvider::register() $this->app->bind(PaymentGateway::class, StripePaymentGateway::class);
A class with a single implementation, used only inside its own layer, needs no contract.
๐๏ธ The Domain layer depends on Eloquent
This is a deliberate trade-off, and it is worth stating explicitly. clean-arch:install generates App\Domain\Shared\BaseModel, which extends Illuminate\Database\Eloquent\Model, and every model produced by clean-arch:make-domain extends it. The Domain layer is therefore free of Application and Infrastructure imports (that is what the generated rules enforce), but it is not free of the framework.
If you need a persistence agnostic domain, this package is not the right starting point.
๐ Transactions
Generated actions do not open a transaction. When a use case has an invariant that only holds if several writes, or a read and a write, happen atomically, the action opens it itself (with lockForUpdate() when it reads before writing). Callers may still wrap it in a larger transaction, since Laravel nests them with savepoints. Mail, events and jobs go in DB::afterCommit(), so nothing leaves the system before the data is committed.
๐ก Examples
๐๏ธ Creating a Product domain
php artisan clean-arch:make-domain Product
๐ฎ Using in controller
class ProductsController extends Controller { public function __construct( private CreateProductAction $createProductAction ) {} public function store(CreateProductRequest $request): JsonResponse { $product = $this->createProductAction->execute($request->validated()); return response()->json([ 'data' => new ProductResource($product), 'message' => 'Product created successfully' ], 201); } }
An action never receives the HTTP request. The controller passes $request->validated(), an array, and models already resolved. A readonly DTO is fine when several callers must normalise the same input.
๐ Classes without a generator
DTOs, policies, domain exceptions and Filament panels have no clean-arch command. Create them straight in their layer, not in a Laravel default folder to move them afterwards.
| Class | Where | How |
|---|---|---|
| Readonly DTO | app/Application/DTOs |
php artisan make:class Application/DTOs/RegistrationData |
| Policy of a domain model | a Policies folder next to the model, app/Domain/Articles/Policies |
php artisan make:class Domain/Articles/Policies/ArticlePolicy |
| Domain exception | an Exceptions folder next to the model, app/Domain/Articles/Exceptions |
php artisan make:class Domain/Articles/Exceptions/ArticleAlreadyPublishedException |
| Filament resources, pages, widgets | app/Infrastructure/Filament |
make:filament-resource, after pointing the panel at that folder |
Laravel's policy discovery walks up from the model namespace, so App\Domain\Articles\Policies\ArticlePolicy is found for App\Domain\Articles\Models\Article (and for App\Domain\Articles\Article) without registering anything. make:policy writes to app/Policies, outside the layers. A policy only imports domain classes, so it breaks no rule.
A domain exception, App\Domain\Articles\Exceptions\ArticleAlreadyPublishedException, states a broken business rule. Make it extend PHP's DomainException (or another SPL exception), so the domain still imports nothing from the other layers, and have an action throw it. Turning it into an HTTP response is the job of the infrastructure layer, for example with ->withExceptions() in bootstrap/app.php. The DomainException, BusinessLogicException and ValidationException that clean-arch:install writes to Infrastructure/Exceptions cannot be thrown from an action or a model: importing them breaks application_no_infrastructure_imports or domain_no_infrastructure_imports.
A Filament panel is an input adapter like a controller. Point the panel provider at the infrastructure layer before generating anything:
->discoverResources(in: app_path('Infrastructure/Filament/Resources'), for: 'App\\Infrastructure\\Filament\\Resources') ->discoverPages(in: app_path('Infrastructure/Filament/Pages'), for: 'App\\Infrastructure\\Filament\\Pages') ->discoverWidgets(in: app_path('Infrastructure/Filament/Widgets'), for: 'App\\Infrastructure\\Filament\\Widgets')
make:filament-resource then writes there by itself. Its --resource-namespace option is ignored for a namespace the panel does not discover: the command falls back to app/Filament and overwrites what is there. The panel provider itself stays in app/Providers.
โ๏ธ Configuration
clean-arch:install writes config/clean-architecture.php. It skips any file that already exists, so editing the config or a generated base class is safe to keep across reinstalls. Pass --force to overwrite them instead. You can also publish the config on its own:
php artisan vendor:publish --tag=clean-architecture-config
Every make-* command and clean-arch:generate-package follow the same rule for the files they write. A command that only ever writes one file (make-action, make-service, make-controller, make-observer, make-listener, make-job, make-mail, make-notification, make-export) refuses to overwrite an existing target, prints an error naming the path, and exits with a failure code, so a script or an AI agent rerunning a generator notices instead of losing hand written code. A command that writes several files (make-domain, clean-arch:generate-package) skips the ones that already exist and still writes the rest, printing a Skipped: line for each. Pass --force on any of them to overwrite instead.
๐ Directories
directories is read by clean-arch:install and the make-* commands, which write the generated classes at those paths, and by clean-arch:make-arch-rules, which turns them into the namespaces and the class sets of the generated config. The layer namespaces are derived from the same values, so app/Core/Domain with a default_namespace of Acme becomes Acme\Core\Domain.
'default_namespace' => 'App', 'directories' => [ 'domain' => 'app/Domain', 'application' => 'app/Application', 'infrastructure' => 'app/Infrastructure', ],
When the config file is not published, the defaults above are used.
The package does not edit your autoloader. Laravel maps App\ to app/ in composer.json, which covers every directory under app/ as long as default_namespace stays App. Any other combination needs a PSR-4 entry of its own, otherwise the classes are generated but cannot be loaded:
| Configuration | Generated namespace | Entry to add under autoload.psr-4 |
|---|---|---|
app/Core/Domain with App |
App\Core\Domain |
none |
app/Domain with Acme |
Acme\Domain |
"Acme\\": "app/" |
src/Domain with App |
App\src\Domain |
"App\\src\\": "src/" |
Two prefixes can point to the same directory, so "Acme\\": "app/" sits next to Laravel's "App\\": "app/". Run composer dump-autoload after editing composer.json.
โ Validation rules
Every rule can be turned off by name under validation.rules. A rule set to false is left out of the config written by clean-arch:make-arch-rules. All of them except no_commands_in_infrastructure and no_classes_outside_layers are enabled by default, and a project without a published config file gets the same set.
'validation' => [ 'rules' => [ 'domain_no_application_imports' => true, 'domain_no_infrastructure_imports' => true, 'application_no_infrastructure_imports' => true, 'no_observers_in_domain' => true, 'no_jobs_in_infrastructure' => true, 'no_commands_in_infrastructure' => false, 'no_classes_outside_layers' => false, ], ],
no_commands_in_infrastructure is off by default. A console command is an input adapter, much like an HTTP controller: it reads arguments and options, prints output and calls an action, which holds the business logic. Keeping it in Application would force the Application layer to depend on Illuminate\Console. Turn the rule on if you prefer commands in Application/Console/Commands.
Some projects send mail and notifications straight from an action, importing App\Infrastructure\Mail or App\Infrastructure\Notifications without an interface in between. Turning application_no_infrastructure_imports off to accept that would also hide the imports you still want reported. List the accepted namespaces under validation.application_infrastructure_allowed instead:
'validation' => [ 'application_infrastructure_allowed' => ['Mail', 'Notifications'], ],
Values are relative to the infrastructure layer, so they keep working with custom directories and default_namespace. With the example above an action importing App\Infrastructure\Mail\ArticleMail passes, while one importing App\Infrastructure\Http\Controllers\Controller or App\Infrastructure\Filament\ArticleResource is still reported. The list is empty by default, and an empty list generates exactly the same phparkitect.php as before. An invalid entry (not a string, or empty) makes clean-arch:make-arch-rules fail without writing the file. After changing the key, regenerate the file with php artisan clean-arch:make-arch-rules --force.
๐งฑ No classes outside the layers
The other rules only read the three layer directories, so code left in app/Http, app/Models, app/Actions or app/Filament is never checked and phparkitect check stays green on an app that is half Laravel folders and half layers. no_classes_outside_layers closes that gap: every class under the root namespace has to reside in one of the three layers, or in a namespace listed under validation.outside_layers_allowed.
'validation' => [ 'rules' => [ 'no_classes_outside_layers' => true, ], 'outside_layers_allowed' => ['Providers'], ],
The rule is off by default, because a Laravel app reports its whole app/Http and app/Models, and everything else it ships outside the layers, until that code has been moved, for example with clean-arch:install --migrate-app.
The root is the top level directory the three layers share, app with the defaults, and its namespace is derived like the layer namespaces, so App or the configured default_namespace. Layers nested deeper, such as app/Core/Domain, still have app as their root, so app/Http keeps being checked. When the layers do not share a top level directory (for example src/Domain next to app/Application), or one of them sits directly in the project root, clean-arch:make-arch-rules fails with a message and writes nothing. Turn the rule off for such a layout.
With the rule on, the generated file scans the root directory once instead of the three layer directories. The layer rules still only apply to their own namespaces, so every class is checked once and no violation is reported twice.
validation.outside_layers_allowed lists namespaces relative to the root namespace that may stay outside the layers. It defaults to ['Providers']: Laravel registers service providers from bootstrap/providers.php, and make:provider and the packages that publish a provider write them to app/Providers. Add the folders a framework or package discovers by convention and that you keep where they are, for example 'Policies' (policy auto discovery looks next to the models), 'Livewire' or 'Filament'. An invalid entry (not a string, or empty) makes clean-arch:make-arch-rules fail without writing the file.
๐ Custom validation messages
validation.custom_messages controls whether clean-arch:make-domain generates the messages() method in the form requests it creates. It defaults to true.
'validation' => [ 'custom_messages' => false, ],
Set it to false and the generated Create*Request and Update*Request classes will omit the messages() method entirely. The default rules() and authorize() methods are unaffected, and the output remains valid PHP either way.
Note the keys under validation serve different purposes. The rules subgroup, application_infrastructure_allowed and outside_layers_allowed are read by clean-arch:make-arch-rules, while custom_messages is read by clean-arch:make-domain at generation time. They are kept together so that a single published config file is the only place to look.
๐๏ธ Optional base classes
generation.extend_base_classes (default true) controls whether generated services extend BaseService and generated actions extend BaseAction. Set it to false to produce standalone classes:
'generation' => [ 'extend_base_classes' => false, ],
You can also override the config per invocation with --no-base on make-domain, make-service, or make-action. The flag always wins:
php artisan clean-arch:make-service Order --no-base php artisan clean-arch:make-action CreateOrder Order --no-base php artisan clean-arch:make-domain Brand --no-base
The BaseService and BaseAction classes created by clean-arch:install remain in Application/Services and Application/Actions regardless. Only the extends clause and its use statement are omitted.
๐๏ธ Model directory
generation.model_directory (default 'Models') controls the subfolder the domain model is generated under, inside each domain's directory. It is read by every command that writes or imports the model, make-domain as well as the standalone make-action, make-controller, make-export, make-job, make-mail, make-notification, make-observer and make-service, so a domain stays consistent no matter which command touches it next.
'generation' => [ 'model_directory' => 'Models', ],
Set it to null or an empty string to generate the model directly inside the domain directory, with no subfolder:
'generation' => [ 'model_directory' => null, ],
clean-arch:make-domain User then writes app/Domain/Users/User.php, declaring App\Domain\Users\User, instead of app/Domain/Users/Models/User.php declaring App\Domain\Users\Models\User.
Any other single segment replaces Models, for example 'Entities' produces app/Domain/Users/Entities/User.php declaring App\Domain\Users\Entities\User. Surrounding slashes are trimmed, so '/Entities/' behaves the same as 'Entities'.
โ๏ธ Job prefix
generation.job_prefix (default 'Process') controls the prefix make-job and make-domain put in front of the generated job, in the class name as well as in the file name. clean-arch:make-job Article writes app/Application/Jobs/ProcessArticleJob.php declaring ProcessArticleJob.
'generation' => [ 'job_prefix' => 'Handle', ],
The same command then writes HandleArticleJob.php. Set it to null or an empty string to generate the job under its own name, ArticleJob.php. The prefix is also what the command strips from the name you pass, so make-job HandleArticleJob stays HandleArticleJob instead of becoming HandleHandleArticleJobJob.
๐ Web controller path
generation.web_controller_path (default 'Http/Controllers/Web') controls where make-controller --web writes, relative to the infrastructure layer directory, and the namespace the generated controller declares. API controllers are not affected: --api always writes to Http/Controllers/Api.
'generation' => [ 'web_controller_path' => 'Http/Controllers', ],
clean-arch:make-controller Report --web then writes app/Infrastructure/Http/Controllers/ReportController.php declaring App\Infrastructure\Http\Controllers. Backslashes and surrounding slashes are accepted, so 'Web\Controllers' and '/Web/Controllers/' behave the same. Set it to null or an empty string to write the controller in the infrastructure layer itself.
๐ค Moving User into the Domain in an existing app
clean-arch:install --user-in-domain is written for a fresh app. On an app that already has data, queued jobs and third party packages, renaming the User class is a data migration as much as a code change. The table below lists what breaks and what to do about it.
| What breaks | Why | Remedy |
|---|---|---|
User::factory() |
The factory name is derived from the model namespace, so the resolver looks for Database\Factories\Domain\Users\Models\UserFactory |
Add newFactory() to the model, returning \Database\Factories\UserFactory::new(), and a protected $model = User::class to the factory |
Polymorphic *_type columns |
Rows hold the old class name, App\Models\User |
Register Relation::morphMap(['user' => User::class]), then run a migration that updates every *_type column holding App\Models\User to user. Do it in the same deploy as the code change |
| Broadcast notification channel | The private channel is named after the notifiable class, private-App.Models.User.{id} |
Rename the channel in routes/channels.php and in the Echo listeners, or keep the old name by returning it from receivesBroadcastNotificationsOn() on the model until the frontend catches up |
| Jobs already queued | A serialized job holds the old class name and fails to unserialize | Drain the queue before deploying, or keep a class alias for one release |
| Package config naming the model | Filament, Cashier, Sanctum, Permission and others store the FQCN in their own config or tables | Search config/ for App\Models\User after the move, and check any package table that stores a model class |
Two more notes:
enforceMorphMap()is stricter thanmorphMap(), it throws on any polymorphic model that is not mapped. It is the right call once every polymorphic model of the app is in the map, and a source of exceptions while packages such as an activity log or a media library still register their own.- Laravel's generators recreate
app/Modelsandapp/Http. Use theclean-arch:make-*commands once the move is done.
๐ค AI guidelines (Laravel Boost)
This package ships AI guidelines and an agent skill for Laravel Boost, at the paths the Boost documentation gives package authors:
resources/boost/guidelines/core.blade.php, a short always in context brief on the three layers, the dependency direction and theclean-arch:*commands.resources/boost/skills/clean-architecture-development/SKILL.md, loaded on demand, covering how to generate a domain, where each class belongs, and how to keepphparkitect checkgreen.
Install Boost 2.5 or higher with composer require laravel/boost --dev then php artisan boost:install, selecting this package when Boost asks which third party guidelines and skills to install.
On an app that already has Boost installed, php artisan boost:update offers the newly detected package only when it runs in an interactive terminal. Run without interaction, or from a Composer script such as the post-update-cmd the Laravel skeleton ships, it skips the question and leaves the package out, so neither the guideline nor the skill is installed. In that case add the package to packages in boost.json yourself, then run the update again:
"packages": [ "plin-code/laravel-clean-architecture" ]
Boost then installs the guideline and the clean-architecture-development skill, and records the skill under skills in boost.json by itself. This was checked against Boost 2.10.
๐ ๏ธ Development
This package uses several tools to maintain code quality:
๐ง Code Quality Tools
- ๐จ Laravel Pint - Code formatting and style fixing
- ๐ PHPStan - Static analysis for finding bugs
- ๐งช PEST - Modern testing framework built on PHPUnit
- ๐ญ Orchestra Testbench - Laravel package testing
๐ Available Scripts
# ๐งช Run tests composer test # ๐ Run tests with coverage composer test-coverage # ๐จ Fix code style composer format # ๐ Check code style without fixing composer format-test # ๐ Run static analysis composer analyse # โจ Run all quality checks composer quality
๐ Development Setup
- ๐ฅ Clone the repository
- ๐ฆ Install dependencies:
composer install - โจ Run quality checks:
composer quality
๐ค Contributing
Pull requests are welcome! ๐ For major changes, please open an issue first to discuss what you would like to change.
Please make sure to update tests as appropriate and follow our Contributing Guidelines. ๐
๐ License
MIT ๐
