Download the PHP package ahmedsaed/laravel-ddd without Composer

Laravel DDD

[!WARNING] Experimental Beta — v0.2.0-beta.3

Laravel DDD is still in beta. Commands, generated structures, and configuration may change before 1.0. Review CHANGELOG.md and UPGRADING.md before updating, and evaluate the package carefully before using it in production.

Laravel DDD provides an opinionated Context structure and Artisan generators for Laravel applications. Each bounded Context separates Domain, Application, Infrastructure, and Presentation code while continuing to use Laravel's container, routes, events, queues, mail, Eloquent, migrations, and testing tools.

The package creates directories and conservative class templates, discovers Context providers and Listeners, registers Context migration paths, and checks some dependency rules. It does not choose Context boundaries, design the business model, or prove that an application follows Domain-Driven Design.

This structure is most useful in applications with distinct business areas or teams that want explicit module boundaries. It is often unnecessary for a small CRUD application or short-lived prototype.

Requirements

Installation

Install the beta, configure Context autoloading, and create the first Context:

Laravel normally discovers AhmedSaed\LaravelDdd\LaravelDddServiceProvider through Composer. If package discovery is disabled, add it to bootstrap/providers.php.

New installations use project-root contexts/ and the Contexts namespace. ddd:install adds that PSR-4 mapping to the application's root composer.json and runs composer dump-autoload. It is safe to run again and refuses to replace a conflicting mapping.

If the application needs a different Context root or namespace, publish and edit the configuration before running ddd:install:

This is the package's only publishing tag; generator stubs are not published. See Configuration for supported customizations.

Quick start

Generate a few components in the new Order Context:

Generated classes are deliberately small. Add the real invariants, fields, methods, mappings, and schema for the application.

The Context command creates OrderDatabaseSeeder. Add OrderSeeder::class to its $this->call(...) list when the child seeder should run with Context seeding. Then inspect the architecture and database plan:

The migration aliases use Laravel's registered migration paths; they are not Context-isolated operations. Read Context migrations and seeders before using rollback, reset, refresh, or fresh commands.

On a new Context, --with-aggregate can add only Domain/Aggregates/Order.php and Domain/Repositories/OrderRepository.php; no business methods are invented.

Generated Context structure

By default, php artisan ddd:make-context Order creates:

Config and Providers are uppercase; resources and tests are lowercase. The command also creates API and web route files plus Infrastructure/Persistence/Eloquent/Seeders/OrderDatabaseSeeder.php. It does not create sample business classes or frontend entry files. --with-vite creates only vite.config.js and uses the root application's Node dependencies.

Architecture

Dependencies point toward the business rules:

• Domain owns Aggregates, Entities, Value Objects, Domain Events, repository contracts, and business rules. Keep it independent of Eloquent, HTTP, queues, cache, mail, and external SDKs.
• Application owns Use Cases, DTOs, Queries, orchestration, and optional contracts. It may depend on Domain, but not on the Context's Infrastructure or Presentation.
• Infrastructure implements persistence and other technical adapters. Keep Laravel Listeners, Jobs, and Mailables directly in Infrastructure/Listeners, Infrastructure/Jobs, and Infrastructure/Mail.
• Presentation owns routes, middleware, Form Requests, Resources, controllers, responses, and console entry points.

ddd:check enforces a documented subset of these rules by inspecting PHP namespaces and imports. Passing it does not prove that the architecture or business model is correct. See Architecture and the Architecture checker.

Domain Events and Listeners

Generate a Domain Event with ddd:make-event. If a Context needs to publish recorded events, opt in when creating it or add the publisher later:

The optional publisher consists of an Application contract, a Laravel Infrastructure adapter, and a provider binding. Laravel Listeners are created in Infrastructure/Listeners and discovered automatically for enabled Contexts:

--event accepts configured Context:EventName shorthand or a fully qualified PHP class name. The package does not provide an outbox, broker integration, retries, or external delivery guarantees. See Domain Events and integrations.

Migrations and seeders

Context migrations are normal Laravel migrations stored with the Context that owns the schema. Enabled Context providers register their migration paths, so native Laravel commands and ddd:migrate* aliases see the same complete path set unless an explicit Laravel --path is supplied.

Migration filenames must be globally unique across database/migrations and all registered Context migration paths. The package checks supported native and DDD migration command boundaries before Laravel begins migration work.

[!CAUTION] migrate:fresh and ddd:migrate-fresh wipe every table on the selected connection. Supplying a Context migration path does not make the wipe Context-only.

ddd:seed runs the conventional root seeder for one enabled Context or all enabled Contexts. It does not replace Laravel's application-level db:seed behavior.

Structural cache

ddd:cache stores Context provider and Listener discovery in the configured manifest. It does not cache provider method bodies, bindings, Domain Event classes, or business logic.

Successful ddd:make-context, ddd:make-provider, ddd:make-event-publisher, and ddd:make-listener runs clear the DDD manifest. ddd:make-event and manual binding edits do not. Failed generation leaves an existing manifest untouched.

Development falls back to live discovery after invalidation. In production, rebuild the DDD manifest explicitly:

If the deployment uses Laravel's event cache, rebuild it with php artisan event:cache after ddd:cache. Use php artisan ddd:clear to remove only the DDD manifest.

Documentation

• Getting started
• Architecture and terminology
• Command reference
• Generator behavior
• Configuration reference
• Architecture checker
• Context migrations and seeders
• Domain Events and integrations
• Modular Context runtime
• Persistence and search read models
• Example walkthrough
• Best practices
• Troubleshooting
• Upgrading
• Changelog