creating-action

Laravel Boost DDD

Pragmatic, Laravel-native Domain-Driven Design for Laravel Boost.

Laravel Boost DDD teaches your coding agents how to apply Domain-Driven Design without fighting Laravel.

It provides Laravel Boost with opinionated guidelines, 11 task-specific agent skills, and Pest architecture tests so that feature work consistently follows the same architectural boundaries.

The goal is not to turn every Laravel application into enterprise architecture. The goal is to give business complexity a clear place to live.

The approach keeps Eloquent, policies, events, queues, and Laravel's usual entry points. Business behavior belongs in Domain, use cases belong in Application, and external integrations belong in Infrastructure. Repositories, Data objects, and services are introduced only when the work gives them a purpose.

Adoption happens as you work on the application. New capabilities follow the DDD structure; existing code stays where it is until a migration is part of the task. Installing the package gives the agent that direction for feature work, bug fixes, and refactoring. It does not move application code or authorize a wider rewrite.

What does it change?

Without architectural guidance, a coding agent can easily put authorisation, business rules, database writes, external APIs, and event dispatching into the same controller or service.

Laravel Boost DDD gives the agent a shared set of decisions for where that code belongs.

For example, a request to:

Add the ability for a customer to cancel an order.

might result in:

app/
├── Application/
│   └── Orders/
│       └── Actions/
│           └── CancelOrder.php
│
├── Domain/
│   └── Orders/
│       ├── Models/
│       │   └── Order.php
│       └── Events/
│           └── OrderCancelled.php
│
└── Http/
    └── Controllers/
        └── CancelOrderController.php

Installation

The package requires PHP ^8.3, Laravel's Illuminate Support ^12.0|^13.0, and Laravel Boost ^2.9. Composer resolves the compatible versions and installs Boost if it is missing. Pest must also be available in the application, because the installer checks for it before making changes.

From your Laravel application's root, install the package as a development dependency:

composer require --dev maiobarbero/laravel-boost-ddd

If the application does not already use Pest, add it as a development dependency and initialize its test setup before continuing:

composer require --dev pestphp/pest
vendor/bin/pest --init

Then run the package installer:

php artisan boost-ddd:install

The command adds maiobarbero/laravel-boost-ddd to Boost's configured packages, retaining the existing package selections. It calls Boost's installer with guidelines and skills enabled, then publishes tests/Architecture/DddArchitectureTest.php without forcing an overwrite of an existing file.

If Boost already has agents configured, the command reuses them without prompting. Otherwise, follow Boost's prompts to choose your agents, keeping this package selected. The command does not enable Boost's Model Context Protocol (MCP) server configuration; if you also need those tools, configure them separately with php artisan boost:install --mcp.

Run the architecture tests

vendor/bin/pest tests/Architecture

The installer publishes the test file, but does not edit your PHPUnit configuration. If phpunit.xml or phpunit.xml.dist only includes Unit and Feature suites, add this inside <testsuites> so the architecture checks run with the rest of your tests:

<testsuite name="Architecture">
    <directory>tests/Architecture</directory>
</testsuite>

Checks for absent layers or directories are skipped. This is expected in an application that has not yet introduced App\Domain or App\Application. Once code enters those namespaces, it is covered by the rules. Legacy code elsewhere remains outside that scope.

How the code is organized

The guidelines organize business code by capability, such as Orders or Billing. A capability folder does not automatically represent a separate bounded context; capabilities within the same context can collaborate directly.

As an example: order's cancel() method checks whether cancellation is allowed and changes its state. The CancelOrder Action authorizes the actor, invokes that behavior, and saves the model. If cancellation also writes an audit record, the Action owns the transaction that keeps the writes together. Application coordinates event dispatch so external reactions happen after commit.

That division also defines the dependency boundaries. Domain does not depend on Application, Infrastructure, or delivery code. Application does not depend on Infrastructure or delivery code. When either layer needs an outer dependency, it defines a contract, Infrastructure implements it, and a Laravel service provider binds the two. Container lookups and custom facades must respect the same boundaries.

Direct Eloquent persistence remains the default. A simple authorized read can stay in a controller; a scalar argument does not need a Data object around it. Jobs and listeners invoke Actions for meaningful use cases, while Actions prefer events for asynchronous follow-up work.

The order cancellation example connects the model, Action, authorization, transaction, event, and tests. The full core guidelines describe the conventions agents receive.

Included skills

The core guidelines establish the shared rules. The skills provide guidance for particular tasks, including changes to existing code. Whether a skill is selected depends on the agent and the task.