README

Laravel DDD Starter Kit
Enterprise-grade Domain-Driven Design foundation for Laravel

About Laravel DDD Starter Kit

The Laravel DDD Starter Kit provides a clean, scalable, enterprise-ready project structure built on Laravel 12, implementing Domain-Driven Design (DDD) and CQRS patterns — without modifying Laravel's core.

This starter kit is designed as if Laravel natively supported DDD out-of-the-box, while maintaining:

• ✅ Full compatibility with Laravel's conventions
• ✅ Eloquent ORM, Service Container, Providers, Routes, Middleware
• ✅ Zero framework hacks or overrides
• ✅ Complete Laravel ecosystem integration (Sanctum, Pest, Pint, etc.)

Perfect for teams and solo developers building large, modular, maintainable applications with clear separation of concerns.

Why DDD + CQRS?

Domain-Driven Design

• Bounded Contexts: Isolate business domains (User, Order, Payment, etc.)
• Ubiquitous Language: Code mirrors business terminology
• Rich Domain Models: Business logic lives in entities, not controllers
• Strategic Design: Clear boundaries between different parts of your application

CQRS (Command Query Responsibility Segregation)

• Commands: Write operations (CreateUser, UpdateOrder)
• Queries: Read operations (GetUserById, ListOrders)
• Handlers: Dedicated classes for each use case
• DTOs: Type-safe data transfer between layers

Key Features

🏗️ Clean Architecture Layers

┌─────────────────────────────────────┐
│         UI / HTTP Layer             │  Controllers, Routes, API
├─────────────────────────────────────┤
│       Application Layer             │  Commands, Queries, DTOs, Handlers
├─────────────────────────────────────┤
│         Domain Layer                │  Entities, Value Objects, Services
├─────────────────────────────────────┤
│     Infrastructure Layer            │  Eloquent, Repositories, External APIs
└─────────────────────────────────────┘

⚡ Built-In Artisan Generators

Create complete DDD modules from the terminal:

php artisan ddd:context Order        # Create bounded context
php artisan ddd:entity Order Order   # Create aggregate root
php artisan ddd:vo Order OrderId     # Create value object
php artisan ddd:use-case Order PlaceOrder  # Command + Handler + DTO
php artisan ddd:eloquent-model Order Order # Model + Repository
php artisan ddd:controller Order PlaceOrder --type=api  # Controller

📦 Modular Installation System

Add external modules as optional features using the stub system:

php artisan make:cms-stubs           # Generate CMS module stubs
php artisan install:cms              # Install CMS module into your app

This approach keeps your application lean by only including the functionality you need.

🧱 Framework-Independent Domain

• Pure PHP domain layer
• No Laravel dependencies in business logic
• Fully testable without framework
• Easy to migrate or extract

🧪 Testing Ready

• Pest 4 integration
• Browser testing support
• Separate unit and feature tests
• Factory pattern for test data

Installation

Create New Project

composer create-project m4rkhenzel/laravel-ddd-starter my-app
cd my-app

Configure Environment

cp .env.example .env
php artisan key:generate

Setup Database

# Configure your database in .env
php artisan migrate

Start Development Server

php artisan serve

Visit http://localhost:8000 — you're ready to build!

Directory Structure

my-app/
├── app/
│   ├── Domain/                      # 🎯 Pure business logic
│   │   ├── Shared/
│   │   │   ├── Contracts/           # Repository interfaces
│   │   │   ├── Exceptions/          # Domain exceptions
│   │   │   └── ValueObjects/        # Shared VOs (Money, Email, etc.)
│   │   │
│   │   └── {Context}/               # Bounded Context (User, Order, etc.)
│   │       ├── Entities/            # Aggregate roots
│   │       ├── ValueObjects/        # Context-specific VOs
│   │       ├── Repositories/        # Repository interfaces
│   │       ├── Services/            # Domain services
│   │       └── Exceptions/          # Context exceptions
│   │
│   ├── Application/                 # 🔄 Use cases (CQRS)
│   │   └── {Context}/
│   │       ├── Commands/            # Write operations
│   │       ├── Queries/             # Read operations
│   │       ├── Handlers/            # Command/Query handlers
│   │       └── DTO/                 # Data Transfer Objects
│   │
│   ├── Infrastructure/              # 🔌 External integrations
│   │   ├── Persistence/
│   │   │   └── Eloquent/{Context}/
│   │   │       ├── {Entity}Model.php            # Eloquent models
│   │   │       └── {Entity}RepositoryEloquent.php  # Implementations
│   │   └── Providers/
│   │       └── DddServiceProvider.php
│   │
│   └── Http/
│       └── Controllers/             # 🌐 Thin HTTP controllers
│           └── {Context}/
│
├── routes/
│   ├── api.php                      # API routes
│   └── web.php                      # Web routes
│
└── tests/
    ├── Feature/                     # Integration tests
    ├── Unit/                        # Unit tests
    └── Browser/                     # Browser tests (Pest 4)

Quick Start Guide

1. Create Your First Bounded Context

php artisan ddd:context Product

This creates the complete folder structure for the Product context:

• app/Domain/Product/
• app/Application/Product/
• app/Infrastructure/Persistence/Eloquent/Product/

2. Define Your Aggregate Root

php artisan ddd:entity Product Product

Edit app/Domain/Product/Entities/Product.php:

<?php

namespace App\Domain\Product\Entities;

use App\Domain\Product\ValueObjects\ProductId;
use App\Domain\Product\ValueObjects\Price;

final class Product
{
    public function __construct(
        private ProductId $id,
        private string $name,
        private Price $price,
        private bool $isActive = true
    ) {
    }

    public function activate(): void
    {
        $this->isActive = true;
    }

    public function deactivate(): void
    {
        $this->isActive = false;
    }

    public function updatePrice(Price $newPrice): void
    {
        $this->price = $newPrice;
    }

    // Getters...
    public function id(): ProductId
    {
        return $this->id;
    }

    public function name(): string
    {
        return $this->name;
    }

    public function price(): Price
    {
        return $this->price;
    }

    public function isActive(): bool
    {
        return $this->isActive;
    }
}

3. Create Value Objects

php artisan ddd:vo Product Price

Edit app/Domain/Product/ValueObjects/Price.php:

<?php

namespace App\Domain\Product\ValueObjects;

use InvalidArgumentException;

final readonly class Price
{
    public function __construct(
        private float $amount,
        private string $currency = 'USD'
    ) {
        if ($amount < 0) {
            throw new InvalidArgumentException('Price cannot be negative');
        }
    }

    public function amount(): float
    {
        return $this->amount;
    }

    public function currency(): string
    {
        return $this->currency;
    }

    public function equals(Price $other): bool
    {
        return $this->amount === $other->amount
            && $this->currency === $other->currency;
    }
}

4. Create a Use Case

php artisan ddd:use-case Product CreateProduct

This generates:

• CreateProductCommand.php
• CreateProductHandler.php
• CreateProductDTO.php

Edit the handler app/Application/Product/Handlers/CreateProductHandler.php:

<?php

namespace App\Application\Product\Handlers;

use App\Application\Product\Commands\CreateProductCommand;
use App\Application\Product\DTO\CreateProductDTO;
use App\Domain\Product\Entities\Product;
use App\Domain\Product\Repositories\ProductRepositoryInterface;
use App\Domain\Product\ValueObjects\ProductId;
use App\Domain\Product\ValueObjects\Price;

final readonly class CreateProductHandler
{
    public function __construct(
        private ProductRepositoryInterface $productRepository
    ) {
    }

    public function handle(CreateProductCommand $command): CreateProductDTO
    {
        $product = new Product(
            id: ProductId::generate(),
            name: $command->name,
            price: new Price($command->price, $command->currency)
        );

        $this->productRepository->save($product);

        return new CreateProductDTO(
            id: $product->id()->value(),
            name: $product->name(),
            price: $product->price()->amount(),
            currency: $product->price()->currency()
        );
    }
}

5. Create Eloquent Model & Repository

php artisan ddd:eloquent-model Product Product

This creates:

• ProductModel.php (Eloquent model)
• ProductRepositoryEloquent.php (Repository implementation)

6. Create API Controller

php artisan ddd:controller Product CreateProduct --type=api

Edit app/Http/Controllers/Product/CreateProductController.php:

<?php

namespace App\Http\Controllers\Product;

use App\Application\Product\Commands\CreateProductCommand;
use App\Application\Product\Handlers\CreateProductHandler;
use App\Http\Controllers\Controller;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

final class CreateProductController extends Controller
{
    public function __construct(
        private readonly CreateProductHandler $handler
    ) {
    }

    public function __invoke(Request $request): JsonResponse
    {
        $validated = $request->validate([
            'name' => 'required|string|max:255',
            'price' => 'required|numeric|min:0',
            'currency' => 'required|string|size:3',
        ]);

        $command = new CreateProductCommand(
            name: $validated['name'],
            price: $validated['price'],
            currency: $validated['currency']
        );

        $dto = $this->handler->handle($command);

        return response()->json($dto, 201);
    }
}

7. Register Routes

Add to routes/api.php:

use App\Http\Controllers\Product\CreateProductController;

Route::post('/products', CreateProductController::class);

8. Test Your API

curl -X POST http://localhost:8000/api/products \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MacBook Pro",
    "price": 2499.99,
    "currency": "USD"
  }'

Testing

Run All Tests

php artisan test

Run Specific Test File

php artisan test tests/Feature/Product/CreateProductTest.php

Filter Tests

php artisan test --filter=CreateProduct

Example Feature Test

Create tests/Feature/Product/CreateProductTest.php:

<?php

use App\Infrastructure\Persistence\Eloquent\Product\ProductModel;

it('creates a product successfully', function () {
    $response = $this->postJson('/api/products', [
        'name' => 'Test Product',
        'price' => 99.99,
        'currency' => 'USD',
    ]);

    $response->assertCreated()
        ->assertJsonStructure([
            'id',
            'name',
            'price',
            'currency',
        ]);

    expect(ProductModel::count())->toBe(1);
});

it('validates required fields', function () {
    $response = $this->postJson('/api/products', []);

    $response->assertUnprocessable()
        ->assertJsonValidationErrors(['name', 'price', 'currency']);
});

Available Artisan Commands

DDD Generators

Command	Description
ddd:context {name}	Create a new bounded context
ddd:entity {context} {name}	Create an aggregate root entity
ddd:vo {context} {name}	Create a value object
ddd:use-case {context} {name}	Create command + handler + DTO
ddd:eloquent-model {context} {name}	Create Eloquent model + repository
ddd:controller {context} {name}	Create a thin controller
ddd:repository {context} {name}	Create repository interface
ddd:service {context} {name}	Create domain service

Module Management

Command	Description
make:cms-stubs	Generate CMS module stub files
install:cms [--force]	Install CMS module from stubs

Modular Installation System

The Laravel DDD Starter Kit includes a powerful modular installation system that allows you to add optional features without bloating your core application.

How It Works

1. Generate Stubs: Create pre-configured module files
2. Install Modules: Copy files to your application structure
3. Keep Lean: Only install what you need

Example: CMS Module

Step 1: Generate CMS Stubs

php artisan make:cms-stubs

This creates a complete Article management system in stubs/cms/:

stubs/cms/
├── Domain/Article/
│   ├── Entities/Article.php
│   ├── ValueObjects/
│   │   ├── ArticleId.php
│   │   └── Slug.php
│   └── Repositories/ArticleRepositoryInterface.php
├── Application/Article/
│   ├── Commands/
│   ├── Queries/
│   ├── Handlers/
│   └── DTO/
├── Infrastructure/Persistence/Eloquent/Article/
│   ├── ArticleModel.php
│   └── ArticleRepositoryEloquent.php
└── database/
    ├── migrations/
    └── seeders/

Step 2: Install the CMS Module

php artisan install:cms

This command:

• Copies all files to the correct DDD layers
• Runs database migrations
• Optionally seeds sample data
• Clears application cache

The Article domain is now part of your application!

Step 3: Register Repository Binding

Add to app/Infrastructure/Providers/DddServiceProvider.php:

$this->app->bind(
    \App\Domain\Article\Repositories\ArticleRepositoryInterface::class,
    \App\Infrastructure\Persistence\Eloquent\Article\ArticleRepositoryEloquent::class
);

Creating Your Own Modules

You can create similar installation commands for any feature:

1. Create a MakeYourModuleStubsCommand
2. Generate stub files following DDD structure
3. Create an InstallYourModuleCommand to copy files
4. Keep modules optional and installable on-demand

Benefits:

• Clean separation of concerns
• Only install features you need
• Easy to share modules between projects
• Maintains DDD architecture

Best Practices

1. Keep Domain Pure

• No Laravel dependencies in Domain/ layer
• Use interfaces for external dependencies
• All business rules in entities and value objects

2. Use Value Objects

• Wrap primitives (Email, Money, OrderId)
• Validation in constructor
• Immutable objects

3. Single Responsibility

• One command/query per use case
• One handler per command/query
• Thin controllers (just validation + dispatch)

4. Repository Pattern

• Interfaces in Domain/
• Eloquent implementations in Infrastructure/
• Inject via Service Provider

5. Test Coverage

• Unit tests for domain logic
• Feature tests for use cases
• Browser tests for critical flows

Architecture Decisions

Why Separate Eloquent Models?

Domain entities are pure PHP classes focused on business logic. Eloquent models in Infrastructure/ handle database persistence. This allows:

• Testing domain logic without database
• Switching ORMs if needed
• Clear separation of concerns

Why CQRS?

Separating commands (writes) from queries (reads) provides:

• Clear intent in code
• Easier optimization (different read/write paths)
• Better scalability
• Simplified testing

Why Bounded Contexts?

Large applications need clear boundaries:

• Prevents "big ball of mud"
• Enables team autonomy
• Allows independent evolution
• Reduces cognitive load

Roadmap

• ✅ Packagist integration
• ✅ Laravel 12 support
• ✅ Complete artisan generators
• ✅ CQRS pattern implementation
• 🚧 Complete example contexts (User, Order)
• 🚧 Event sourcing support (optional)
• 🚧 CI/CD templates (GitHub Actions)
• 🚧 Documentation website
• 🚧 Video tutorials

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

The Laravel DDD Starter Kit is open-sourced software licensed under the MIT License.

Resources

• Packagist: m4rkhenzel/laravel-ddd-starter
• GitHub: LaravelDDD
• Laravel Documentation: https://laravel.com/docs
• DDD Resources: Domain-Driven Design Reference

Support

If you discover any security vulnerabilities, please email directly instead of using the issue tracker.

For bugs and feature requests, please use the GitHub issue tracker.

Made with ❤️ for the Laravel community