README

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

🆕 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)
• 🔧 Service
• 🌐 API Controller
• 📝 Form Requests (Create, Update)
• 📤 API Resource
• 🗃️ Database migration
• 🧪 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.

✅ Architecture validation

php artisan clean-arch:validate

This command checks your codebase for layer dependency violations (for example, Domain code importing from Infrastructure). It returns exit code 1 when violations are found, making it suitable for use in CI pipelines.

Clean Architecture Validation
=============================

  ✓ Domain has no Application imports
  ✓ Domain has no Infrastructure imports
  ✓ Application has no Infrastructure imports
  ✓ No Observers in Domain
  ✓ No Jobs in Infrastructure
  ✓ No Commands in Infrastructure
  ✓ No duplicate Services directory

No violations found.

🛠️ Available commands

• clean-arch:install - 🏗️ Install Clean Architecture structure
• clean-arch:make-domain {name} - 🆕 Create a complete new domain
• clean-arch:make-action {name} {domain} - ⚡ Create a new action
• clean-arch:make-service {name} - 🔧 Create a new service
• clean-arch:make-controller {name} - 🌐 Create a new controller
• clean-arch:make-observer {name} {domain} - 👁️ Create a new observer
• clean-arch:make-listener {name} - 👂 Create a new listener
• clean-arch:make-job {name} - ⏳ Create a new job
• clean-arch:make-mail {name} - 📧 Create a new mailable
• clean-arch:make-notification {name} - 🔔 Create a new notification
• clean-arch:make-export {name} - 📤 Create a new export
• clean-arch:validate - ✅ Validate architecture dependency rules
• clean-arch:generate-package {name} {vendor} - 📦 Generate a new package

📂 Project structure after clean-arch:install

app/
├── Domain/                          # Pure business logic
├── Application/                     # Use cases and orchestration
│   ├── Actions/
│   ├── Services/
│   ├── Jobs/
│   ├── Listeners/
│   └── Console/Commands/
└── Infrastructure/                  # Framework adapters
    ├── Http/
    │   ├── Controllers/Api/
    │   ├── Middleware/
    │   ├── Requests/
    │   └── Resources/
    ├── UI/
    ├── Mail/
    ├── Notifications/
    ├── Observers/
    ├── Exports/
    ├── Validation/
    └── Exceptions/

📂 Generated structure after clean-arch:make-domain User

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
│   └── Services/
│       └── UserService.php
└── Infrastructure/
    └── Http/
        ├── Controllers/
        │   └── Api/
        │       └── UsersController.php
        ├── Requests/
        │   ├── CreateUserRequest.php
        │   └── UpdateUserRequest.php
        └── Resources/
            └── UserResource.php

🏛️ Clean Architecture Principles

This package implements Clean Architecture principles:

1. 🎯 Domain Layer: Contains business logic and entities
2. ⚡ Application Layer: Contains use cases and application logic
3. 🏗️ Infrastructure Layer: Contains implementation details (controllers, database, etc.)

🔗 Dependencies

• 🎯 Domain Layer: Does not depend on any other layer
• ⚡ Application Layer: Depends only on Domain Layer
• 🏗️ Infrastructure Layer: Depends on Application and Domain Layers

💡 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,
        private ProductService $productService
    ) {}

    public function store(CreateProductRequest $request): JsonResponse
    {
        $product = $this->createProductAction->execute($request);
        
        return response()->json([
            'data' => new ProductResource($product),
            'message' => 'Product created successfully'
        ], 201);
    }
}

⚙️ Configuration

The configuration file config/clean-architecture.php allows you to customize:

• 🏷️ Default namespace
• 📁 Directory paths
• ✅ Validation options
• 📊 Logging settings

🛠️ 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

1. 📥 Clone the repository
2. 📦 Install dependencies: composer install
3. ✨ 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 📜