Download the PHP package creativecrafts/laravel-domain-driven-design-lite without Composer

Pragmatic, Laravel-native DDD modules with generators, safety rails, and CI helpers – without drowning you in ceremony.

✅ Quick Start (60s)

📚 Contents

• Start Here
• What is DDD‑Lite?
• Architecture Overview
• Requirements
• Installation
• Provider & Publishing
• Getting Started (QuickStart)
• Command Reference
• Project Initialization
• Enforcing Strict Architecture with Deptrac + PHPStan
• Limitations: Circular Dependencies at Scale
• Safety Rails: Manifest & Rollback
• Package Quality: PHPStan, Deptrac & Pest
• Common Workflows
• Testing Philosophy
• Design Principles
• Troubleshooting
• Changelog
• Security
• Credits
• License

🧩 Start Here

If you only read three sections:

• Getting Started (QuickStart) – a 60‑second setup.
• Common Workflows – the most practical end‑to‑end examples.
• Command Reference – every command and flag in one place.

🧭 What is DDD-Lite?

DDD-Lite is a developer-tooling package that helps you organise your Laravel 12+ application into modular, domain-oriented boundaries.

It gives you:

• A module structure (modules/<ModuleName>) with a clear split between:
  • App/ – adapters & Laravel-specific glue (controllers, requests, models, providers, repositories)
  • Domain/ – pure PHP domain code (DTOs, actions, contracts, queries, value objects)
• Generators for:
  • DTOs, Actions, Contracts, Repositories, Value Objects
  • Queries and Query Builders
  • Aggregate Roots
  • Controllers, Requests, Models, Migrations, Providers, Routes
• A conversion engine to move existing app/* code into modules:
  • Discovers move candidates (controllers, models, requests, actions, DTOs, contracts)
  • Applies moves with AST-based namespace rewrites
• Safety rails for all file operations:
  • Every run produces a Manifest (with creates/updates/deletes/moves/mkdirs)
  • --dry-run on everything
  • Rollback by manifest id
• Quality & CI tooling:
  • Publishable PHPStan & Deptrac configs
  • Optional Pest architecture tests
  • ddd-lite:doctor / ddd-lite:doctor:domain / ddd-lite:doctor-ci to keep modules healthy

The goal is: clean seams, safer refactors, better testability – without requiring you to rewrite your entire app in one go.

🧱 Architecture Overview

A DDD-Lite module lives under modules/<ModuleName>:

✅ Rules of thumb

Domain:

• Pure PHP, no hard dependency on Laravel.
• Orchestrates use cases with Actions (e.g. CreateTripAction).
• Talks to the outside world through Contracts (e.g. TripRepositoryContract).
• Uses DTOs and Value Objects for data.

App:

• Typical Laravel adapters (controllers, form requests, models).
• Implements contracts using Eloquent (e.g. TripRepository).
• Wires things together using module service providers.

⚙️ Requirements

• PHP: ^8.3
• Laravel (Illuminate components): ^12.0
• Composer

Recommended dev dependencies in your app (for quality tooling integration):

• larastan/larastan
• deptrac/deptrac
• pestphp/pest
• pestphp/pest-plugin-laravel
• pestphp/pest-plugin-arch

⚙️ Installation

Require the package in your Laravel app (usually as a dev dependency):

This package is primarily a developer tool (scaffolding, conversion, quality helpers), so installing under --dev is recommended. Laravel’s package discovery will automatically register the service provider.

📦 Provider & Publishing

DDD-Lite ships with stubs and quality configs you can copy into your app.

Stubs (module scaffolding & generators)

To publish the stubs:

This will create:

• stubs/ddd-lite/*.stub – templates for:
  • DTOs, Actions, Contracts, Repositories, Value Objects, Aggregates
  • Controllers (including an --inertia variant)
  • Requests
  • Models & migrations
  • Module providers and route/event providers
  • Routes (web & api)

You typically don’t need to touch these unless you want to customise the generated code style.

Quality tooling

To seed PHPStan, Deptrac and Pest architecture tests into your application:

This will (in your app):

• Create phpstan.app.neon with sensible defaults for app/ + modules/
• Create deptrac.app.yaml describing layer boundaries (Http, Models, Domain, Modules, etc.)
• Add tests/ArchitectureTest.php with baseline rules:
  • No debug helpers (dd, dump, var_dump, …)
  • No stray env() calls
  • Enforce strict types

Safe publishing tip

• Run once, then commit the generated files so changes are visible in code review.

You can also publish selectively:

Customising stubs (recommended workflow)

1) Publish the stubs once:

2) Edit the generated files under stubs/ddd-lite/ in your app (e.g. tweak DTO or controller templates). 3) Re-run the generator command. Your customised stubs are now the source of truth.

Tip: keep your stub changes small and version-controlled so upgrades are easy to diff.

✅ Enforcing Strict Architecture with Deptrac + PHPStan

This package ships publishable templates you can wire into your app to enforce module boundaries and strict layered architecture.

1) Publish the configs

This creates (in your app):

• deptrac.app.yaml – layer rules for app/ and modules/
• phpstan.app.neon – analysis paths + defaults for modules/

2) Deptrac: strict module boundaries

The template already defines layers like Http, Models, Repositories, Domain, Providers, and ModulesAll. To enforce stricter module boundaries, extend the ruleset to constrain Modules\*\Domain and Modules\*\App explicitly.

Example (add to deptrac.app.yaml):

For cross‑module rules, add a shared kernel (e.g. Modules\Shared) and only allow ModuleDomain to depend on Modules\Shared (not other modules).

3) PHPStan: include modules and tighten strictness

The published phpstan.app.neon already includes:

• paths: [app, modules]
• Larastan extension include

To go stricter, set level: max and enable stricter checks:

4) CI integration

Use the existing Composer scripts:

⚠️ Limitations: Circular Dependencies at Scale

• Deptrac detects circular dependencies at the layer graph level. If you do not model modules as distinct layers, cycles across modules may be invisible.
• Dynamic resolution (service container bindings, facades, late static calls) can hide cycles that Deptrac cannot infer statically.
• Large modular systems can produce noisy or slow analysis. You may need to scope rules (paths, exclude_files) or split configs per module to keep feedback fast.
• PHPStan does not detect architectural cycles; it only validates types and static correctness. Use Deptrac (or Pest Arch tests) for structure enforcement.

🚀 Getting Started (QuickStart)

We’ll build a simple Planner module with a Trip aggregate.

1) Scaffold a module

This creates modules/Planner with:

• Providers (module, route, event) under App/Providers
• Routes in Routes/api.php and Routes/web.php
• Domain folders (Actions, DTOs, Contracts, Queries, ValueObjects)
• Tests folders

Core flags:

• --dry-run – preview actions without writing
• --fix-psr4 – auto-rename lowercased module folders to proper PascalCase
• --shared – scaffold a Shared Kernel (domain‑only) module
• --rollback= – undo a previous scaffold
• --force – overwrite content when needed (with backups)

For full details see: docs/module-scaffold.md

2) Generate a DTO

This generates modules/Planner/Domain/DTO/CreateTripData.php:

• Properly typed constructor
• readonly by default
• Optional unit test (unless --no-test is passed)

3) Generate a domain Action

This creates Domain/Actions/Trip/CreateTripAction.php similar to:

4) Implement the repository & bind it Create an Eloquent repository in modules/Planner/App/Repositories/TripRepository.php (or let ddd-lite:make:repository scaffold it):

Then wire the contract to the implementation:

ddd-lite:bind edits your module provider so that:

is registered.

5) Expose via HTTP Generate a controller + request:

✅ Recipes

Recipes index

• Controller orchestrates a Domain action
• Payments module walkthrough
• Orders module creation + structure

Controller Orchestrates a Domain Action (HTTP stays in App)

This is the missing piece most people want: the controller only adapts HTTP input and delegates to the Domain action. The action stays HTTP‑free.

1) Generate the pieces

2) Domain action (pure business logic)

3) Form request (HTTP concerns only)

4) Controller (orchestrates, no business logic)

5) Minimal feature test (verifies orchestration)

Boundary rule of thumb: App layer knows HTTP; Domain layer never does.

Payments Module Walkthrough (DTO → Contract → Repository → Action)

This compact slice ties the pieces together with real code, while keeping Domain pure and App infrastructural.

1) Generate the artifacts

2) DTO (Domain)

3) Contract (Domain)

4) Repository (App, Eloquent adapter)

5) Action (Domain, orchestrates business rules)

Boundary rule of thumb: Domain owns the contract and action; App wires the implementation and persistence.

🧠 DDD-Lite in Practice: Example Flow

A typical “vertical slice” in a module:

• DTO: CreateTripData – validated input from HTTP or CLI.
• Action: CreateTripAction – orchestrates creation, enforces invariants.
• Contract: TripRepositoryContract – interface for persistence.
• Repository: TripRepository (Eloquent) – implements contract.
• Controller: TripController@store – adapts HTTP to the action.

Generators help you keep this shape consistent across modules without hand-rolling boilerplate every time.

✅ Advanced Workflows

Multi‑Tenant SaaS Structure + Boundary Enforcement (Deptrac + PHPStan)

This section shows a concrete, enforceable layout for multi‑tenant apps, with shared domain concepts and strict module boundaries.

1) Recommended module layout

2) Shared Kernel (domain‑only) Use --shared to keep it pure (no HTTP/Routes):

3) Shared domain concepts (example)

4) Tenancy boundary (example contract)

5) App layer adapter uses tenancy, Domain stays pure

✅ Deptrac: Enforce Module Boundaries

Create a deptrac.yaml in your host app (this repo ships a package example, but apps should define their own rules):

6) Run Deptrac with DDD‑Lite

✅ PHPStan: Block Cross‑Module Dependencies

Add module‑level ban rules in your app’s phpstan.neon to prevent accidental imports:

Then override per‑module configs (example for Projects):

Boundary rule of thumb: Domains depend only on Shared + their own contracts. App layer can orchestrate across modules via contracts and adapters.

Limitations & Mitigations (circular dependencies)

• Deptrac can detect cycles but won’t tell you how to break them. When a cycle appears, move shared contracts/value objects into Shared/Domain and depend on those instead of cross‑module concrete classes.
• Avoid App ↔ Domain cycles by keeping infrastructure in App and interfaces in Domain.
• If you must allow a dependency for a transition period, document it explicitly and remove it once the migration is complete.

Shared concepts + cross‑module communication (tenant‑safe patterns)

• Put common value objects and contracts in Shared/Domain (e.g., TenantId, Money, Period).
• Expose inter‑module capabilities via Domain contracts (e.g., Billing\Domain\Contracts\Invoices), and bind App implementations in the owning module.
• Prefer application services in App for orchestration across modules; Domain actions should stay within their module boundary.

Tenant isolation guidelines

• Always pass TenantId into Domain actions or repositories; never infer tenancy inside Domain from HTTP or globals.
• In App repositories, scope every query by tenant (e.g., ->where('tenant_id', $tenantId->value)).
• For cross‑module reads, use contracts that accept TenantId explicitly to prevent accidental leakage.

Safe Refactor Workflow with --dry-run + Rollback

Use dry‑run previews and manifests to refactor large features into modules safely.

1) Plan the move (no files written)

Syntax reminders

• --paths is a comma‑separated list of directories (no spaces).
• --plan-moves discovers candidates only (no writes).

2) Apply moves with review (writes manifest)

The output includes a manifest id:

3) Inspect what was changed

Each action records the file path and the type (create/update/move).

How to read dry‑run output

• move indicates a file will be relocated into the module.
• update indicates a namespace or import rewrite.
• If you see unexpected paths, narrow --paths before applying moves.

4) Rollback if needed

5) Refactor with dry‑run safety (scaffold + bind)

6) Verification checklist

• Review dry‑run output for unexpected paths.
• Use ddd-lite:manifest:show to confirm changes before committing.
• If anything looks off, rollback immediately and re‑run with a narrower --paths scope.

Error handling tips

• If a command fails after writing files, rollback using the manifest id printed in the output.
• For repeated refactors, keep the manifest id in your PR notes.
  • If you hit unexpected rewrites, run ddd-lite:convert <Module> --report to review planned namespace changes before applying.

Before/After tree (concrete example)

Before (legacy feature in app/):

After (moved into modules/Billing):

Convert Monolith app/ → Invoicing Module (with namespace rewrites)

This is the complete, safe workflow: scaffold the module first, then plan + apply moves.

1) Scaffold the module (required)

2) Plan the conversion (no files written)

3) Review and apply moves (writes manifest)

4) Confirm namespace rewrites

5) Rollback if needed

Notes

• The conversion engine rewrites namespaces to Modules\\Invoicing\\... during moves.
• Use --paths to keep scope tight and predictable for large refactors.

Create an Orders Module + Typical Structure

1) Create the module

2) Typical directory structure (Domain vs App)

3) Register + adapter example The module provider is created and registered automatically during ddd-lite:module. To connect App infrastructure to Domain, bind a contract in the module provider:

Then use the contract inside a Domain action, while App implementations remain Eloquent‑based.

4) Minimal flow (Controller → Action → Repository)

🧭 Project Initialization

For a guided, one‑shot setup (stubs, quality configs, optional module, and CI snippet):

Common flags:

• --module= – scaffold a starter module (e.g. Core)
• --no-module – skip module scaffolding
• --publish=all|quality|stubs|none
• --ci=show|write|none
• --ci-path=... – write workflow to a custom path
• --yes – non‑interactive defaults

🧰 Command Reference

All commands share a consistent UX:

• --dry-run – print what would happen; no files written; no manifest saved.
• --force – overwrite when content changes (backups are tracked in manifests).
• --rollback= – revert a previous run (see Manifest section below).

Command Index

• Bootstrap: ddd-lite:init
• Scaffolding: ddd-lite:module
• Generators: ddd-lite:make:*
• Wiring: ddd-lite:bind
• Conversion: ddd-lite:convert
• Quality: ddd-lite:publish:quality, ddd-lite:doctor, ddd-lite:doctor:domain, ddd-lite:doctor-ci, ddd-lite:boundaries
• Manifests: ddd-lite:manifest:list, ddd-lite:manifest:show
• Stubs: ddd-lite:stubs:diff, ddd-lite:stubs:sync
• Modules: ddd-lite:modules:list

Cheat Sheet

1. Module scaffolding & conversion

ddd-lite:module Scaffold a new module skeleton:

Key flags:

• name (required) – module name in PascalCase.
• --dry-run – preview only.
• --force – overwrite files if they exist.
• --shared – scaffold a Shared Kernel (domain‑only) module.
• --fix-psr4 – rename existing lowercased module folders to PSR-4 PascalCase.
• --rollback= – rollback a previous scaffold.

See docs/module-scaffold.md for details.

ddd-lite:convert Discover and optionally apply moves from app/* into modules:

To use the namespace rewriting and AST-based moves, install nikic/php-parser:

composer require --dev nikic/php-parser

Important options:

• module – target module name.
• --plan-moves – discover move candidates and print a plan (no writes).
• --apply-moves – actually apply moves (AST-safe namespace rewrites).
• --review – interactive confirmation per move (with --apply-moves).
• --all – apply all moves without prompts.
• --only=controllers,models,requests,actions,dto,contracts – include kinds.
• --except=... – exclude kinds.
• --paths=... – comma-separated paths to scan.
• --with-shims – include shim suggestions in the printed plan.
• --suggest-contracts – print suggested contracts/bindings for moved models/actions.
• --export-plan=path.json – write discovered move plan to JSON.
• --dry-run, --force, --rollback=.

Use this to gradually migrate a legacy app into DDD-Lite modules.

Safe conversion workflow

• Start with --plan-moves and export the plan (--export-plan=...) for review.
• Apply with --review before --all.
• Keep the manifest id; roll back with --rollback=<id> if needed.

2. Domain generators

ddd-lite:make:dto Generate a DTO under Domain/DTO:

• module – module name.
• name – DTO class name.
• --in= – optional subnamespace inside Domain/DTO.
• --props= – name:type[|nullable] comma-separated.
• --readonly – enforce readonly class (default: true).
• --no-test – skip generating a test.

ddd-lite:make:action Generate a domain action in Domain/Actions:

• --in= – optional subnamespace.
• --method= – method name (default __invoke).
• --input= – parameter type preset: none|ulid|FQCN.
• --param= – parameter variable name.
• --returns= – void|ulid|FQCN.
• --no-test – skip test.

ddd-lite:make:contract Generate a domain contract:

• --methods= – semi-colon separated: name:ReturnType(args...).
• --with-fake – generate a Fake implementation under tests/Unit/fakes.
• --no-test – skip the contract test.

ddd-lite:make:repository Generate an Eloquent repository for an aggregate:

Creates:

• App/Repositories/TripRepository.php
• Optional tests (unless --no-test).

ddd-lite:make:value-object Generate a value object:

• --scalar= – backing scalar type: string|int|float|bool.
• --no-test – skip generating a test.
• --with-validation-test – include a validation test that expects InvalidArgumentException.

By default, a test is created at: modules/<Module>/tests/Unit/Domain/ValueObjects/<Name>Test.php

Example: Email value object with validation (egulias/email-validator)

1) Install the validator in your app:

2) Generate the value object:

3) Update the generated file:

Path: modules/Users/Domain/ValueObjects/Email.php

4) Instantiate in your Domain layer (e.g. in an Action):

5) Add a minimal test (Pest):

Path: modules/Users/tests/Unit/EmailTest.php

ddd-lite:make:aggregate-root Generate an aggregate root base:

Useful for richer domain modelling around key aggregates.

Query side

• ddd-lite:make:query – generate a Query class in Domain/Queries.
• ddd-lite:make:query-builder – generate a QueryBuilder helper.
• ddd-lite:make:aggregator – generate an Aggregator to combine queries.
  • add --no-test to skip generating tests for each of these.

Example:

3. App-layer generators

ddd-lite:make:model Generate an Eloquent model in App/Models:

Options:

• --table=, --fillable=, --guarded=
• --soft-deletes
• --no-timestamps

ddd-lite:make:migration Generate a migration under Database/migrations:

• module? – module name (optional).
• name? – migration base name.
• --table= – table name.
• --create= – shortcut for table creation.
• --path= – override path (defaults to module migrations).
• --force, --dry-run, --rollback=.

ddd-lite:make:controller Generate a controller:

• --resource – standard Laravel resource methods.
• --inertia – generate methods that return Inertia pages.
• --suffix= – class suffix (default Controller).

ddd-lite:make:request Generate a form request:

• --suffix= – class suffix (default Request).

4. Binding & wiring

ddd-lite:bind Bind a domain contract to an implementation in the module provider:

• module – module name.
• contract – contract short name or FQCN.
• implementation – implementation short name or FQCN.
• --force – skip class existence checks (e.g. when generating ahead of time).

5. Manifest commands Every write operation (scaffolding, generate, convert, publish, doctor fixes) is tracked via a Manifest.

ddd-lite:manifest:list List manifests:

Options:

• --module= – filter by module.
• --type= – mkdir|create|update|delete|move.
• --after=, --before= – ISO8601 bounds for created_at.
• --json – machine-readable output.

ddd-lite:manifest:show Inspect a single manifest:

Shows the tracked operations for that run (created files, backups, moves, deletions, etc.).

6. Doctor & Quality commands

ddd-lite:publish:quality (Described earlier) – publishes PHPStan, Deptrac, and Pest Arch configuration/stubs into your app.

ddd-lite:doctor Run structural checks on your modules and wiring:

Checks things like:

• Module provider registration
• Route/service provider wiring
• PSR-4 inconsistencies
• Missing or mis-wired module components

Flags:

• --module= – limit to a specific module.
• --fix – attempt automatic fixes (provider edits, PSR-4 renames, etc.).
• --json – JSON report for tooling.
• --deep – run doctor:domain and doctor-ci after base checks.
• --prefer=file|class – strategy when class and filename mismatch.
• --rollback= – undo fixes.

ddd-lite:doctor:domain Run domain purity checks via Deptrac:

Options:

• --config= – Deptrac YAML config.
• --bin= – path to deptrac executable.
• --json – JSON summary.
• --strict – treat uncovered as failure.
• --stdin-report= – use pre-generated Deptrac JSON report.
• --fail-on= – violations|errors|uncovered|any.

ddd-lite:doctor-ci Run both structural and domain checks in CI:

• --paths= – paths to scan (defaults to modules/ and bootstrap/app.php).
• --fail-on=none|any|error – CI failure policy.
• --json – CI-friendly JSON result.

Use this in your CI pipeline to enforce module health.

ddd-lite:boundaries Alias for ddd-lite:doctor:domain to run Deptrac boundary checks with a friendlier name.

ddd-lite:modules:list List modules and (optionally) show health:

ddd-lite:stubs:diff Compare package stubs to your customized stubs:

ddd-lite:stubs:sync Sync missing or changed stubs into your app:

🧪 Safety Rails: Manifest & Rollback

DDD-Lite never silently edits your app.

For each command run that changes files:

• A Manifest is written with:
  • mkdir, create, update, delete, move records
  • Backups of overwritten files
• You can inspect manifests with:
  • ddd-lite:manifest:list
  • ddd-lite:manifest:show {id}
• You can revert a run by passing --rollback=<manifest-id> to the original command (e.g. ddd-lite:module, ddd-lite:convert, ddd-lite:publish:quality, ddd-lite:doctor).

This makes DDD-Lite safe to use on large, existing codebases.

🧮 Package Quality: PHPStan, Deptrac & Pest

Inside this package:

• phpstan.neon.dist – strict rules for the package itself.
• deptrac.package.yaml – package-level dependency rules.
• tests/ArchTest.php – baseline architecture checks via Pest.

In your application, use:

and then:

Combine this with ddd-lite:doctor-ci in CI for a tight feedback loop.

🧩 Common Workflows

Greenfield project

• Install DDD-Lite.
• Scaffold your first module: ddd-lite:module.
• Generate DTOs, Actions, Contracts, Repositories, Controllers, Requests.
• Set up quality tooling with ddd-lite:publish:quality.
• Wire ddd-lite:doctor-ci into your CI.

Migrating a legacy app

• Install DDD-Lite.
• Scaffold a module for a coherent slice (e.g. Planner, Billing, Users).
• Use ddd-lite:convert with --plan-moves on a subset of app/*.
• Iterate with --apply-moves and --review, keeping an eye on manifests.
• Introduce contracts + repositories for areas you want to harden.
• Run ddd-lite:doctor and ddd-lite:doctor:domain regularly during the migration.

🧪 Testing Philosophy

The package itself is tested with:

• Pest for:
  • Feature tests of console commands
  • Unit tests for internals (filesystem, manifests, planners)
• Architecture tests to protect boundaries.

You’re encouraged to:

• Keep module tests close to modules (under modules//tests).
• Use the provided stubs for DTO / Action / Contract / Repository tests to keep patterns consistent.

🔒 Design Principles

• Domain purity – Domain/ should know nothing about Laravel.
• Explicit boundaries – Domain <-> App contracts are interfaces, not facades.
• Safety first – manifests, backups, --dry-run, --rollback.
• Deterministic generators – running a command twice should be safe and idempotent.
• CI-friendly – all checks and reports can be consumed by automation via JSON / exit codes.

🧰 Troubleshooting

• “Nothing seems to happen when I run a command”
  • Check if you passed --dry-run.
  • Inspect manifests using ddd-lite:manifest:list.
• “I messed up my module structure”
  • Find the relevant manifest id: ddd-lite:manifest:list.
  • Rerun the original command with --rollback=.
• “Deptrac or PHPStan fail after publishing quality configs”
  • Make sure you installed the suggested dev dependencies in your app.
  • Tweak phpstan.app.neon / deptrac.app.yaml to match your project’s structure.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Security

Please review our security policy on how to report security vulnerabilities.

🙌 Credits

• Godspower Oduose
• All Contributors

📄 License

The MIT License (MIT). Please see License File for more information.