Skip to main content

20 docs tagged with "ddd"

View all tags

A Practical Introduction to Laravel × DDD × Clean Architecture

No Laravel experience required. A 20-chapter guide for SPA developers (Vue/React) that explains Laravel as an API backend together with domain-driven design (DDD) and clean architecture, step by step. It covers the theory of value objects, entities, aggregates, and repositories, through to implementation patterns, transactions, testing, and authentication in a Laravel project.

Aggregates — The Consistency Boundary and the Aggregate Root

Explains the DDD aggregate (Aggregate) using the Order aggregate as the example. It covers why the aggregate root is the sole access point, how to decide aggregate boundaries (lifecycle / consistency / transaction / references), choosing between immediate and eventual consistency, referencing across aggregates by ID, and the idea of snapshots.

Conclusion and Next Steps — Introducing DDD Incrementally

Organizes the key points of all 20 chapters of this guide (DDD tactical design / clean architecture / practical techniques / a comprehensive hands-on example), and summarizes a roadmap for incremental adoption—value objects → use case layer → repository → domain events—along with frequently asked questions and recommended books, communities, and learning paths.

Designing the Use Case Layer — Command / Query Separation and DTOs

Explains the design of the application layer (use case layer). Covers its responsibilities of coordinating domain objects, managing transactions, and converting input/output; Command / Query separation based on the CQS principle; Command objects and DTOs; dedicated Query services; and design guidelines such as single responsibility.

Domain Events — Loosely Coupling Aggregates

Explains the DDD domain event (Domain Event) with implementation examples such as OrderConfirmed. It covers loose coupling through event-driven design, the two-phase implementation of recording and dispatching, integration with Laravel Events, synchronous vs asynchronous (ShouldQueue), and the design of idempotency and eventual consistency.

Domain Model and Table Design — Mapping and Indexes

Covers why to design domain-model-first, mapping patterns under the premise that the domain model and tables are not 1:1 (embedding / one aggregate across multiple tables / technical splitting), how the repository absorbs the gap, and index design including the leftmost-prefix rule for composite indexes and its trade-offs.

Domain Services — Business Logic That Does Not Belong to an Entity

Explains the DDD domain service (Domain Service) with implementation examples of discount calculation, stock allocation, and shipping-fee calculation. It covers the criteria for placing logic that spans multiple aggregates and has no infrastructure dependency, the difference from use cases (application services), and design guidelines for avoiding an anemic domain model.

Entities — Domain Objects with an Identifier and a Lifecycle

Explains the DDD entity (Entity) with implementation examples of Order / OrderLine. It covers identity judgment by identifier, the difference from value objects, entity ≠ table, the two factory methods create() / reconstruct(), and state transitions and the encapsulation of business rules using enums.

Error Handling — Mapping Domain Exceptions to HTTP Statuses

Explains error handling in a DDD architecture. Covers an exception hierarchy organized per aggregate, the design of DomainException, mapping to HTTP statuses (404/409/422, etc.) in the Exception Handler, a unified error response, the Result type pattern, a logging strategy, and protecting sensitive information.

In Practice: Implementing the Order System — An Example That Cuts Across All Layers

Integrates the DDD and clean architecture learned so far, implementing the 4 layers (presentation / application / domain / infrastructure) using the order creation and confirmation APIs as the subject. Summarizes each layer's responsibilities, the flow of data transformation, and layered tests (domain / UseCase / Repository) to bring the whole picture together.

Testing Strategy — The Test Pyramid and Layered Testing

Explains the testing strategy for a DDD architecture. Covers the idea of the test pyramid (Unit / Integration / Feature), the benefit of testing the domain layer fast without a DB, minimal use of mocks, Arrange-Act-Assert, descriptive test method names, and the test data builder pattern.

The Repository Pattern — The Boundary Between Domain and Persistence

Implements the repository pattern with Laravel + Eloquent. Covers why the interface lives in the domain layer (DIP / testability), one aggregate = one repository, mapping between entities and Eloquent Models, the N+1 problem and eager loading, mass-assignment protection, and registration in the DI container.

Transaction Management — Where to Place the Consistency Boundary

Explains transaction management using Laravel's DB::transaction(). Covers the ACID properties, when to place transactions inside the Repository (single aggregate) versus the UseCase (multiple aggregates), nested transactions (savepoints), and the implementation and use cases of optimistic and pessimistic locking.

Why DDD — The Limits of the Fat Controller / Fat Model

Organizes the problems that arise when handling complex business logic in traditional Laravel MVC—Fat Controller, Fat Model, and scattered logic—and explains the four benefits gained by adopting DDD: clarifying business rules, resilience to change, testability, and team communication.