Download the PHP package lava83/ddd-foundation without Composer

DDD Foundation for Laravel

[!IMPORTANT]
Currently work in progress! 🚧

A comprehensive toolkit providing foundational building blocks for implementing Domain-Driven Design (DDD) patterns in Laravel 12+ applications. This package offers battle-tested base classes, contracts, and infrastructure components to help you build scalable, maintainable domain-driven applications.

Features

• 🏗️ Aggregate & Entity Base Classes - Ready-to-use foundation for domain entities with built-in versioning and timestamps
• 🎯 Event Sourcing Support - Complete domain event handling with automatic event dispatching via Laravel's event system
• 🔄 Repository Pattern - Abstract repository implementation with entity-model mapping
• 🗺️ Entity-Model Mappers - Clean separation between domain and infrastructure layers
• 🆔 UUID Primary Keys - Built-in UUID support for entities and models
• 🔐 Optimistic Locking - Automatic version tracking to prevent concurrent update conflicts
• 📦 Value Objects - Type-safe value object implementations (MongoObjectId, UUID, Email, Link, Json)
• 🔌 Service Layer Pattern - Interfaces for application and domain services
• ⚡ Transaction Support - Automatic transaction handling in repositories

Requirements

• PHP: 8.3+
• Laravel: 12+
• Dependencies:
  • illuminate/support
  • illuminate/database
  • illuminate/events
  • spatie/laravel-data
  • ramsey/uuid

Installation

Install via Composer:

Core Concepts

Entity Hierarchy

Quick Start Guide

1. Creating an Entity

Entities are domain objects with identity that can change over time:

2. Creating an Aggregate Root

Aggregates are the main entry points for domain operations and manage domain events:

3. Implementing a Repository

Repositories provide collection-like access to aggregates:

4. Creating Entity-Model Mappers

Mappers handle the translation between domain entities and infrastructure models:

5. Registering Mappers

Create a mapper resolver to manage entity-to-mapper relationships:

Register in your service provider:

6. Working with Domain Events

Create domain events to capture important business occurrences:

Handle events using Laravel Event Subscribers:

Register the subscriber in your EventServiceProvider:

7. Creating Application Services

Application services orchestrate domain operations:

8. Creating Value Objects

Value objects represent descriptive aspects of your domain:

Simple Date Range Value Object Example

Using Built-in Value Objects

Key Features Explained

Automatic Event Dispatching

When you save an aggregate through a repository, domain events are automatically dispatched:

The Repository base class handles this through the dispatchUncommittedEvents() method, which uses Laravel's Illuminate\Events\Dispatcher.

Optimistic Locking

All entities include automatic version tracking to prevent lost updates:

UUID Primary Keys

Models automatically use UUIDs as primary keys by extending the framework's Model base class:

Transaction Support

Repositories automatically wrap save operations in transactions:

Architecture & Layering

Recommended Project Structure

Layer Responsibilities

Domain Layer (Pure PHP, no Laravel dependencies)

• Business logic and rules
• Entities and Aggregates
• Domain events
• Value Objects
• Repository and Service contracts

Application Layer (Minimal Laravel usage)

• Application services (use cases)
• Controllers
• Request validation
• Resource transformers
• Use Laravel helpers like collect() when beneficial

Infrastructure Layer (Full Laravel integration)

• Eloquent models
• Repository implementations
• Entity-Model mappers
• External service integrations
• Database migrations

Service Provider Setup

Register Repositories

Register Application Services

Best Practices

1. Keep Domain Layer Pure

Minimize Laravel dependencies in the domain layer:

2. Use Helper Functions Sparingly

Use Laravel helpers like collect() in domain when beneficial:

3. Always Use Static Factory Methods

Create aggregates through named constructors:

4. Record Events for All State Changes

5. Use Transactions for Aggregate Saves

Always wrap saves in transactions to ensure consistency:

Planned Features

• ⏳ Soft Deletes - Soft delete support at entity, aggregate, and model layers
• ⏳ Additional Value Objects - More built-in value objects (Money, Address, etc.)
• ⏳ Advanced Mapper Types - Support for different mapping strategies

Troubleshooting

"No mapper found for entity class"

Ensure you've registered the mapper in your EntityMapperResolver:

"Concurrency Exception"

This indicates two processes tried to update the same aggregate simultaneously. Handle it gracefully:

Events Not Dispatching

Ensure:

1. You're calling save() on the repository (not directly on the model)
2. Your event subscribers are registered in EventServiceProvider
3. Events extend the framework's DomainEvent base class

Contributing

This is currently a private package. For questions or suggestions, contact the maintainer.

License

This package is open-sourced software licensed under the MIT license.

Credits

Built with ❤️ by lava83 for building scalable Laravel applications using Domain-Driven Design principles.