Download the PHP package samuel-nunes/laravel-ddd-toolkit without Composer

Laravel DDD Toolkit

Laravel DDD Toolkit is a Composer package for building large, modular Laravel applications with vertical modules, hexagonal architecture by default, and pragmatic tactical DDD patterns.

Website: samuelnunesdev.github.io/laravel-ddd-toolkit-site

It organizes the application vertically by business capability, such as Order, Payment, Customer, or Billing, while keeping the Laravel experience familiar: Artisan commands, service providers, routes, Eloquent, jobs, listeners, requests, and controllers still work as expected.

This package is intentionally pragmatic. It is not an academic DDD framework, it does not replace Laravel, and it does not force CQRS, Event Sourcing, repositories, or a rigid architecture on every project.

Summary

• Why This Exists
• Compatibility
• Architecture
• Installation
• Quick Start
• Core Commands
• Generated Structure
• Generated Code Example
• Presets
• Discovery Cache
• Architecture Checks
• Configuration
• Repositories And Eloquent
• Custom Stubs
• Contributing
• Development
• License

Why This Exists

Laravel is productive and expressive, but large applications often become hard to navigate when code is grouped mainly by technical layer:

• controllers grow too large;
• services become generic dumping grounds;
• business rules spread across models, requests, jobs, and listeners;
• related files live far apart from each other;
• module boundaries become hard to see;
• teams struggle to change one business area without touching another.

Laravel DDD Toolkit addresses this by encouraging a modular monolith organized by business capability:

Each module is a feature, business capability, subdomain, or bounded context depending on the size of the application.

Compatibility

• PHP: ^8.2
• Laravel components: ^11.0, ^12.0, or ^13.0

Architecture

The toolkit combines two complementary ideas:

The default positioning is:

Dependency direction is separate from execution flow.

Allowed dependency direction:

Typical execution flow:

Ports live in Application/Ports/In and Application/Ports/Out. Adapters live in Infrastructure.

An external integration can act as an anti-corruption layer when it protects the domain from external APIs, payloads, SDK models, or vendor-specific concepts. ACL is treated as a role an integration can play, not as the primary command name.

Installation

The install command creates:

On Laravel 11 and newer, it also registers App\Providers\ModulesServiceProvider in:

If legacy folders such as app/Models, app/Services, or app/Repositories exist, the command may ask if you want to review them. It never removes those folders automatically.

The installer never overwrites an existing AGENTS.md unless --force-agents is explicitly used.

Installer options:

AI-friendly projects

Laravel DDD Toolkit can publish an AGENTS.md file to help AI coding agents understand the architecture of your Laravel project.

If your project already has an AGENTS.md, it will not be overwritten.

To merge Laravel DDD Toolkit instructions into an existing file:

To skip publishing:

To overwrite:

The file guides agents to preserve vertical modules, hexagonal architecture by default, ports in Application, adapters in Infrastructure, a Domain layer without Laravel dependencies, make:module instead of make:domain, and ddd:check before finishing architectural changes.

Quick Start

Create an Order module, define an outbound persistence port, bind it to an Eloquent adapter, and create a use case:

Then run the architecture checker:

Module AI docs

When creating a module, Laravel DDD Toolkit can generate module-level documentation for humans and AI agents.

You can provide context directly:

Or from a file:

To skip AI docs:

Generated files:

These files do not use AI. They are generated from templates using the context provided by the developer.

Core Commands

Create a module:

Create tactical domain and application classes:

Create Ports and Adapters:

Create an external integration:

Run architecture checks and discovery cache commands:

Existing files are not overwritten unless you pass --force.

Generated Structure

By default, make:module creates a vertical module with hexagonal structure:

Domain/Contracts is not created by the default preset. Use explicit ports in Application/Ports/In and Application/Ports/Out instead.

Generated Code Example

An outbound Port is generated as a PHP interface in the application layer:

A persistence Adapter can implement that Port from the infrastructure layer:

When possible, the adapter command also registers the binding in the module provider:

Presets

Hexagonal is the default:

This is equivalent to:

Alternative presets are available when a project needs less or more structure:

• minimal: creates only Domain, Application, and Infrastructure.
• tactical: creates tactical DDD directories without explicit Ports and Adapters.
• full: includes aggregates, ports, adapters, repositories, jobs, listeners, policies, integrations, and providers.

Discovery Cache

The generated ModulesServiceProvider discovers module routes and providers automatically.

It loads route files from:

It registers module service providers from:

For production, cache discovery into a manifest:

The manifest is written to:

Clear it with:

When the cache exists, discovery uses the manifest. When it does not exist, filesystem discovery is used.

Architecture Checks

Run:

By default, this validates basic hexagonal rules:

• Domain must not import Laravel, HTTP foundation, Guzzle, or module Infrastructure classes.
• Application must not import controllers, HTTP requests, or persistence models.
• Infrastructure may depend on Application, Application/Ports, and Domain.

Validate a single module:

The command does not alter files and returns a non-zero exit code when violations are found, so it can be used in CI.

Configuration

The published config lives at:

Default options:

Repositories And Eloquent

Eloquent is supported. Active Record is part of Laravel's productivity story and can coexist with domain-oriented code.

Repositories are disabled by default:

Create repositories or outbound ports only when they solve a real problem, such as hiding complex persistence, integrating external storage, or protecting application/domain code from query details.

Force a repository generation:

For hexagonal persistence boundaries, prefer an outbound port plus an infrastructure adapter:

Custom Stubs

Publish the package stubs when you want to customize generated code:

Published stubs are placed in:

When a custom stub exists there, the generator uses it instead of the package default.

Contributing

Contributions are welcome. Before opening a pull request, run:

Development

Install dependencies:

Run tests:

The test suite uses Orchestra Testbench to validate package behavior against Laravel.

Run static analysis:

Run the full local check:

When PHP or Composer are not available on the host machine, the same checks can be run with the Psalm Docker image:

License

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