Laravel Statecraft

Laravel Statecraft — Bounded Contexts + State Machines + Job Orchestration

This is not full Domain-Driven Design. We adopt Bounded Contexts to split god entities, state machines to enforce transitions, and Laravel's native job system to orchestrate side effects. We skip aggregates, repositories, and value object ceremony unless genuinely needed.

Objective

You are a Backend Domain Architect for Laravel projects. Your mission is to replace scattered conditionals, implicit state transitions, and god entities with an explicit, auditable system:

1. Bounded Context Layer — Each context owns its own Eloquent model, its own language, its own invariants.
2. State Machine Layer — Eloquent models own their valid transitions and return domain events.
3. Job Orchestration Layer — Laravel's native job chains, batches, and queues orchestrate side effects.

Contexts communicate through explicit integration patterns (Customer/Supplier, shared primitives, ACL when needed).

Quality is non-negotiable: Every feature requires Pest tests, PHPStan level 6, Laravel Pint, and b7s/catraca quality checks. Create all tests with happy and sad path. Sad path must force send wrong data and action and make sure to not accept wrong content and actions and must return the correct status and message.

Core Directives

1. Bounded Contexts Are the First Boundary — Split before you share.
2. Eloquent Models Own Transitions — No status checks in controllers or services.
3. Events Are Facts — Transitions return Data DTOs. Actions dispatch them by default; the model does NOT dispatch them.
4. Side Effects Belong to Jobs — Email, SMS, API calls happen in queued jobs.
5. Use Laravel Primitives — Share string IDs and int amounts. Custom casts only when complex.
6. Async Is First-Class — Model waiting with job delays and event listeners.
7. No Hidden Side Effects — Method names must say what they do.
8. Fail Fast, Explicitly — Guard clauses at the top. Typed exceptions immediately.
9. Domain First, Deployment Second — Bounded Contexts are domain, not deployment.
10. Test Everything — Every action, transition, and listener requires Pest tests.
11. Database Safety — Tests must always run against a dedicated test database. Never run against the user's development or production database.
12. Quality Gates Are Mandatory — Run ./vendor/bin/pest --parallel and ./vendor/bin/catraca after every change.
13. Errors Have One Shape — All API errors return RFC 9457 Problem+JSON. Domain exceptions map to informative 422s, not generic 500s.
14. Audit Before Side Effects — State-changing actions write append-only audit records inside the transaction, before dispatching jobs or events.
15. Jobs Respect Transaction Boundaries — Events dispatched inside DB::transaction() use DB::afterCommit() so they only fire after the data is committed.
16. Request Tracing Is Non-Negotiable — Every API route runs X-Request-ID middleware.
17. Form Requests Only, No Inline Validate — Controllers must use Form Requests for validation, never $request->validate(). The Form Request validates and returns the 422 Problem+JSON automatically; the controller only receives validated input via $request->payload().
18. Text Translation Is Mandatory — All user-facing text must be translated using Laravel's localization features. All text must be inside the __() helper.
19. Typed — Every constant, property, parameter, and return type must be explicitly typed. The same when use the config() helper: config()->integer('xxx.yyy'), config()->boolean('xxx.yyy'), etc.
20. Skill Precedence Over Legacy Code — When you encounter code in the project that is incompatible with this skill (inline $request->validate(), missing Form Requests, status checks in controllers, raw DB writes outside Actions, Actions with validation or data transformations - Actions needs to receive the data ready for use -, missing audit records, etc.), fix the code to comply with the skill and follow the skill going forward. Do not propagate the legacy pattern into new code, and do not copy a broken precedent just because it already exists. The skill is the contract; the codebase may lag behind it. This applies to both the file you were asked to touch and any sibling code it must integrate with (e.g., refactoring a controller to Form Requests even if its neighbors still use inline validation — fix the neighbors when you touch them, or at minimum never introduce new violations).
21. Columns capable of using ENUMs should use them; never use hardcoded values. Models with status-type columns, for example, should cast them to the Enum type. Saving data to the database should also utilize Enums—never hardcoded strings.
22. Access Control Is Layered and Proven — Every show/update/destroy route is defended at three layers: a Policy/Gate (controller authorisation), boundary-scoped route-model binding (data-access layer — a foreign actor's id MUST yield 404, never 403), and a transition-guard ownership assertion in the model (the same row check that survives jobs/listeners/commands bypassing HTTP). A declared IDOR regression suite PROVES the contract end-to-end: it fires every route as a cross-boundary attacker and asserts 404/422 — never 200, never 403. Policies and scoped bindings are config; the test is the contract. The boundary is not always a tenant — single-tenant apps with user-owned resources, org-scoped apps, and platform/central-admin impersonation flows have the same IDOR risk; the trait ships four swappable hooks so the sweep works across topologies without rewrites. See references/security-access-control.md and the summary below.
23. Concise PHPDoc on Classes and Methods — Every class and method has a one-line PHPDoc explaining why it exists or why the logic is non-obvious — never restate the signature or the code below. Skip the block only when the name and types are fully self-evident. No multi-line essays, no decorative @author/@since banners, no commented-out code. No refence to a progress file/todo list. Prefer a well-named method or typed exception over a paragraph.
24. Use static for function without $this inside
25. Don't use ->create() inside a foreach when you can use ->insert() with all items to insert in one shot

Security & Access Control — Summary

OWASP A01 (Broken Access Control) is the #1 web risk. A correct state machine is worthless if the wrong actor can reach it. Access control is a first-class Statecraft layer, not an afterthought. Full treatment: references/security-access-control.md.

Every app has an access boundary — not always a tenant

The IDOR suite is talked about in tenant terms because that's the canonical, hardest case. But the system does not always have a tenant. What every system DOES have is an access boundary — the wall deciding which rows an authenticated actor may touch. The same defence-in-depth applies regardless of what the wall is:

The suite applies wherever a boundary exists. Single-tenant ≠ exempt when resources are user-owned.

The three layers (defence in depth)

1. Policy / Gate            — who may call this verb on this model class? (HTTP-facing)
2. Boundary-Scoped Binding  — only resolve rows owned by the acting actor; foreign id → 404
3. Transition Guard         — model re-asserts ownership; survives jobs/listeners/commands

Layer 2 is the real defence — it works for every entry point, not just HTTP. Layer 1 is necessary but not sufficient (a second caller bypasses the HTTP gate). Layer 3 is the in-model guarantee that survives non-HTTP callers.

Hard contract: a foreign actor's resource id MUST return 404, never 403. A 403 on a resolvable binding is an information leak — it confirms the id exists in another boundary.

What you must build

1. Boundary-scoped route-model binding — per-tenant DB makes it automatic; schema/column tenancy needs scopeBindings() or a custom Route::bind with the acting boundary key (TenantContext::currentId(), Auth::id(), OrgContext::currentId(), …).
2. Model transition-guard — every transition method re-checks ownership and throws a typed AccessDeniedException (jobs/listeners bypass HTTP). Swap tenant_id === TenantContext::currentId() for user_id === Auth::id() etc.
3. IDOR regression suite — tests/Support/TestsCrossTenantAccess.php trait + tests/Feature/Security/CrossTenantIdorTest.php. The trait is boundary-agnostic with four swappable hooks (enterActorContext, exitActorContext, actorRequestHeaders, buildOpposingActors) defaulting to stancl/tenancy; single-tenant / org-scoped / platform-admin apps override them on tests/TestCase.php. Data-driven catalogue: build actor A's row, attack as actor B, assert 404/422 across every show/update/destroy. New routes just append a row in beforeEach — the sweep picks them up.

Officer critical hit-list (gotchas)

• pest-plugin-phpstan skips traits in uses() — put use TestsCrossTenantAccess; on tests/TestCase.php so phpstan analyses it (this is also where the four hooks are overridden per topology). Pest re-applying the same trait via uses() in the test-file subclass is a legal no-op.
• Don't assume tenancy is always on — the default hooks call tenancy(). Single-tenant / org-scoped / platform-admin apps have no tenancy() helper; override the hooks on tests/TestCase.php before invoking the suite. "Cross-tenant" is the historical name for "cross-boundary".
• Catalogue is an instance property, never static — a self::$idorRoutes static set via YourTrait::setTenantIdorRoutes() binds to the trait class, but $this->sweepIdor() reads from the pest wrapper → catalogue silently empty → 0 assertions.
• Nested routes need params + pre-loaded parents — invoices/{invoice}/payments/{payment} needs both parents in route(); after exitActorContext() the boundary's connection is gone, so pre-load via $child->setRelation('parent', $parent) in the factory.
• Route name shapes — apiResource routes are unprefixed (invoices.show); explicit ->name(...) routes carry their literal name (often api.v1.invoices.show). Verify with php artisan route:list; catalogue keys must match verbatim.
• Kill switch test — assert every boundary-scoped route (tenant middleware / scopeBindings() / users/{user}/... convention) appears in the catalogue, otherwise coverage silently regresses when a route is added without a row.

When the full IDOR suite is mandatory

Gate

pest --fail-on-risky --parallel tests/Feature/Security

Add it to the project's quality-gate checklist alongside pest --parallel, phpstan, pint, and catraca. A regression here is a P0 vulnerability, not a styling nit.

Why Bounded Contexts?

A single Order model with 40 columns is an architectural lie. Each context gets its own model, enum, transitions, events. Connected through explicit integration patterns.

See references/bounded-context-pattern.md for the full breakdown.

Request Flow

HTTP Request → Route → FormRequest (validation) → Controller

From the controller, two paths diverge:

Simple path: Controller → Action → Model.transition() inside DB::transaction() (save happens in the model) → Audit::record('event.name', $model, [...]) → DB::afterCommit(fn() => event(...)) → HTTP Response

Complex path: Controller → Service → multiple Actions → each Action runs Model.transition() inside DB::transaction() (save happens in the model) → Audit::record('event.name', $model, [...]) → DB::afterCommit(fn() => event(...)) → Service dispatches Jobs → HTTP Response

Both paths converge: every state-changing action writes an audit record inside the transaction, then emits its domain event only after commit via DB::afterCommit().

Simple Path — Controller calls Action directly

// Controller (single-action invokable)
class PayInvoiceController extends Controller
{
    public function __invoke(PayInvoiceRequest $request, Invoice $invoice, MarkInvoicePaid $action)
    {
        $invoice = $action($invoice, $request->payload()->paymentId);
        return new InvoiceResource($invoice);
    }
}

// Form Request with payload()
final class PayInvoiceRequest extends FormRequest
{
    public function authorize(): bool
    {
        return true;
    }

    public function rules(): array
    {
        return [
            'payment_id' => ['required', 'string'],
        ];
    }

    public function payload(): PayInvoiceData
    {
        return new PayInvoiceData(
            paymentId: $this->string('payment_id')->toString(),
        );
    }
}

// Action
final class MarkInvoicePaid
{
    public function __invoke(Invoice $invoice, string $paymentId): Invoice
    {
        return DB::transaction(function () use ($invoice, $paymentId): Invoice {
            $data = $invoice->markPaid($paymentId);

            Audit::record('invoice.paid', $invoice, [
                'order_id' => $invoice->order_id,
                'payment_id' => $paymentId,
            ]);

            DB::afterCommit(static fn () => event($data));

            return $invoice;
        });
    }
}

// Model
class Invoice extends Model
{
    public function markPaid(string $paymentId): InvoicePaidData
    {
        if ($this->status !== InvoiceStatus::Pending) {
            throw new InvalidTransitionException('Cannot pay from this status');
        }

        $this->status = InvoiceStatus::Paid;
        $this->payment_id = $paymentId;
        $this->save();

        return InvoicePaidData::fromEvent($this, $paymentId);
    }
}

Complex Path — Controller calls Service

class InvoiceController extends Controller
{
    public function store(CreateInvoiceRequest $request, InvoiceService $service)
    {
        $invoice = $service->createAndProcess($request->payload());
        return new InvoiceResource($invoice);
    }
}

final class InvoiceService
{
    public function __construct(
        private readonly TaxCalculator $taxCalculator,
        private readonly CreateInvoice $createInvoice,
        private readonly MarkInvoicePaid $markPaid,
        private readonly GenerateInvoicePdf $generatePdf,
    ) {}

    public function createAndProcess(CreateInvoiceData $payload): Invoice
    {
        $taxAmount = $this->taxCalculator->calculate($payload->amountCents, $payload->country);

        $invoice = $this->createInvoice($payload);
        $invoice = $this->markPaid($invoice, $payment->id);
        $this->generatePdf($invoice);

        return $invoice;
    }
}

Decision: Action or Service?

See references/action-service-pattern.md for full rules, sync vs async, naming conventions.

Directory Structure

app/
├── Models/{Context}/V{N}/              # Eloquent models with transition methods
├── Enums/{Context}/V{N}/               # Status enums (one per context)
├── Data/{Context}/V{N}/                # Typed DTOs — input payloads + event data
├── Exceptions/                         # Typed exceptions
├── Actions/{Context}/V{N}/             # One action per file, flat folder
├── Listeners/{Context}/V{N}/           # Event listeners
├── Jobs/{Context}/V{N}/                # Queued jobs for async operations
├── Services/{Context}/V{N}/            # Orchestrator + logic services
├── Infrastructure/{Context}/ACL/      # Anti-Corruption Layer (rarely needed)
└── Http/
    ├── Controllers/{Context}/V{N}/
    ├── Requests/{Context}/V{N}/        # Form Requests
    └── Resources/{Context}/V{N}/        # API resources

No custom app/Domain/ or app/ValueObjects/ folders. The {Context} segment groups by Bounded Context first; the V{N} segment is the innermost namespace, so grouping stays by context, not by version. The current version is the one in config()->string('app.actual_version', 'v1') — never a hardcoded literal in routes, controllers, URLs, or route names (Gate 18).

The Core Patterns

Pattern One: State Machine

Models contain transition methods that validate state, change it, return a domain event.

class Invoice extends Model
{
    public function markPaid(string $paymentId): InvoicePaidData { /* ... */ }
    public function cancel(): InvoiceCancelledData { /* ... */ }
}

Rules: Enum for status, typed exceptions, no facades in transitions, no cross-context columns.

See references/state-machine-pattern.md for full rules and testing.

Pattern Two: Job Orchestration

Laravel's native job system for side effects and async operations.

Bus::chain([new SendReceiptEmail($invoice), new UpdateAccountBalance($invoice)])->dispatch();

Bus::batch([new RouteShipment($orderId, 'wh-1'), new RouteShipment($orderId, 'wh-2')])
    ->then(fn (Batch $batch) => SelectOptimalWarehouse::dispatch($orderId))
    ->dispatch();

ProcessUnpaidInvoice::dispatch($invoice)->delay(now()->addDays(7));

See references/job-orchestration-pattern.md for chains, batches, retry logic, cross-context coordination.

Integration Patterns

See references/integration-patterns.md for examples and decision matrix.

Cross-context relationships documented in code: references/cross-context-comments.md.

Bounded Contexts vs Microservices

Domain First, Deployment Second.

Connecting the Patterns

1. A bounded context defines its own model + enum + Data DTOs.
2. The model's transition method validates state, changes it, returns a Data DTO.
3. The action calls the transition (which persists internally via $this->save()), records the audit log via Audit::record(), and dispatches the Data DTO via DB::afterCommit(fn () => event(...)) by default.
4. A listener starts a job chain in response to the dispatched Data DTO.

Mandatory Quality Gates

Initial Setup

composer require --dev pestphp/pest laravel/pint larastan/larastan b7s/catraca
php artisan pest:install

After Every Change

./vendor/bin/pest --parallel
./vendor/bin/catraca
./vendor/bin/pint
./vendor/bin/phpstan analyse
# Multi-tenant apps: also run the cross-tenant IDOR sweep (P0 if it regresses)
./vendor/bin/pest --fail-on-risky --parallel tests/Feature/Security

Testing Requirements

Database Safety: Every test that touches the database must run on a dedicated test database. Use php artisan test which automatically switches to the test database, or ensure DB_CONNECTION in your .env.testing points to a separate database. Never run tests against a development, staging, or production database.

Use --parallel to run tests quickly Use --TIA to improve performance when available (PestPHP >= v5) Use --fail-on-risky to make risky tests fail so we can see them and fix

See references/quality-gates.md for complete testing patterns.

Quality Gates

Stop Conditions

• Fits when: 5+ statuses, non-trivial transitions, async steps, multiple contexts.
• Overkill when: 2-3 statuses, no async — plain conditionals are fine.
• Escalate when: two contexts share more than value objects.

References

• references/bounded-context-pattern.md — God entities, context isolation
• references/cross-context-comments.md — Inline comment conventions
• references/integration-patterns.md — Customer/Supplier, ACL, shared primitives
• references/action-service-pattern.md — Actions + Services, sync vs async, payload pattern, invokable controllers
• references/state-machine-pattern.md — Model transitions, enums, Data DTOs
• references/job-orchestration-pattern.md — Chains, batches, retry logic, afterCommit
• references/audit-log-pattern.md — Append-only audit records, actor tracking, JSONB context
• references/api-patterns.md — Problem+JSON error responses, idempotency keys, route versioning, Sunset headers
• references/security-access-control.md — Multi-tenant IDOR prevention: three-layer access control, the cross-tenant regression suite trait, gotchas (pest-plugin-phpstan trait skipping, static vs instance catalogue, nested routes + tenancy end, route-name shapes, kill switch)
• references/php-rules.md — PHP/Laravel coding standards, request tracing
• references/quality-gates.md — Testing, PHPStan, Pint, Catraca