PHPackages                             samuel-nunes/laravel-ddd-toolkit - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. samuel-nunes/laravel-ddd-toolkit

ActiveLibrary

samuel-nunes/laravel-ddd-toolkit
================================

A pragmatic tactical DDD toolkit for modular Laravel applications.

v1.0.0(yesterday)01↑2900%MITPHP ^8.2

Since Jul 22Compare

[ Source](https://github.com/SamuelNunesDev/laravel-ddd-toolkit)[ Packagist](https://packagist.org/packages/samuel-nunes/laravel-ddd-toolkit)[ RSS](/packages/samuel-nunes-laravel-ddd-toolkit/feed)WikiDiscussions Synced today

READMEChangelogDependencies (7)Versions (2)Used By (0)

Laravel DDD Toolkit
===================

[](#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](https://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
-------

[](#summary)

- [Why This Exists](#why-this-exists)
- [Compatibility](#compatibility)
- [Architecture](#architecture)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Core Commands](#core-commands)
- [Generated Structure](#generated-structure)
- [Generated Code Example](#generated-code-example)
- [Presets](#presets)
- [Discovery Cache](#discovery-cache)
- [Architecture Checks](#architecture-checks)
- [Configuration](#configuration)
- [Repositories And Eloquent](#repositories-and-eloquent)
- [Custom Stubs](#custom-stubs)
- [Contributing](#contributing)
- [Development](#development)
- [License](#license)

Why This Exists
---------------

[](#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:

```
app/
  Modules/
    Order/
    Payment/
    Customer/
  Shared/

```

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

Compatibility
-------------

[](#compatibility)

- PHP: `^8.2`
- Laravel components: `^11.0`, `^12.0`, or `^13.0`

Architecture
------------

[](#architecture)

The toolkit combines two complementary ideas:

```
Vertical architecture organizes the project by module or business capability.

Hexagonal architecture organizes dependencies inside each module through Ports and Adapters.

```

The default positioning is:

```
Vertical modules
+ Hexagonal architecture inside each module
+ Pragmatic tactical DDD

```

Dependency direction is separate from execution flow.

Allowed dependency direction:

```
Infrastructure -> Application -> Domain
Infrastructure -> Application Ports
Domain does not depend on Infrastructure
Application does not depend on Controllers, Requests, or persistence Models

```

Typical execution flow:

```
HTTP
  -> Controller
  -> Application Use Case
  -> Domain
  -> Port
  -> Adapter

```

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
------------

[](#installation)

```
composer require samuel-nunes/laravel-ddd-toolkit
php artisan ddd:install
```

The install command creates:

```
app/Modules
app/Shared
app/Providers/ModulesServiceProvider.php
config/ddd.php
AGENTS.md

```

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

```
bootstrap/providers.php

```

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:

```
--no-agents
--merge-agents
--force-agents

```

AI-friendly projects
--------------------

[](#ai-friendly-projects)

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

```
php artisan ddd:install
```

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

To merge Laravel DDD Toolkit instructions into an existing file:

```
php artisan ddd:install --merge-agents
```

To skip publishing:

```
php artisan ddd:install --no-agents
```

To overwrite:

```
php artisan ddd:install --force-agents
```

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
-----------

[](#quick-start)

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

```
php artisan make:module Order
php artisan make:port Order OrderRepository --type=out
php artisan make:adapter Order EloquentOrderRepository --port=OrderRepository --type=persistence
php artisan make:usecase Order CancelOrder
```

Then run the architecture checker:

```
php artisan ddd:check --module=Order
```

Module AI docs
--------------

[](#module-ai-docs)

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

```
php artisan make:module Billing
```

You can provide context directly:

```
php artisan make:module Billing --context="Handles invoice issuing, cancellation and invoice queries."
```

Or from a file:

```
php artisan make:module Billing --context-file=docs/billing-context.md
```

To skip AI docs:

```
php artisan make:module Billing --no-ai-docs
```

Generated files:

```
app/Modules/Billing/README.md
app/Modules/Billing/AGENTS.md

```

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

Core Commands
-------------

[](#core-commands)

Create a module:

```
php artisan make:module Order
```

Create tactical domain and application classes:

```
php artisan make:entity Order Order
php artisan make:value-object Customer Email
php artisan make:event Order OrderCancelled
php artisan make:usecase Order CancelOrder
```

Create Ports and Adapters:

```
php artisan make:port Order OrderRepository --type=out
php artisan make:port Order CancelOrderUseCase --type=in
php artisan make:adapter Order EloquentOrderRepository --port=OrderRepository --type=persistence
```

Create an external integration:

```
php artisan make:integration Payment Stripe
```

Run architecture checks and discovery cache commands:

```
php artisan ddd:check
php artisan ddd:cache
php artisan ddd:clear
```

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

Generated Structure
-------------------

[](#generated-structure)

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

```
app/Modules/Order/
├── Domain/
│   ├── Entities/
│   ├── ValueObjects/
│   ├── Events/
│   └── Exceptions/
├── Application/
│   ├── UseCases/
│   ├── DTO/
│   └── Ports/
│       ├── In/
│       └── Out/
└── Infrastructure/
    ├── Http/
    │   ├── Controllers/
    │   ├── Requests/
    │   └── routes.php
    ├── Persistence/
    │   ├── Models/
    │   └── Adapters/
    ├── Integrations/
    └── Providers/

```

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

Generated Code Example
----------------------

[](#generated-code-example)

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

```