# Laravel Clean Architecture

> Implement Domain-Driven Design with typed DTOs, repository interfaces, and single-responsibility Action classes in Laravel. Use when creating domain folders, binding repository contracts in providers, or passing DTOs between layers.

- Skill: `hoangnguyen0403/laravel-clean-architecture` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add hoangnguyen0403/laravel-clean-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hoangnguyen0403/laravel-clean-architecture/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: HoangNguyen0403 (https://skillmd.com/u/hoangnguyen0403)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/hoangnguyen0403/laravel-clean-architecture

---

# Laravel Clean Architecture

## **Priority: P1 (HIGH)**

## Workflow: Add Domain Feature

1. **Create domain folder** — `app/Domains/Order/{Actions,DTOs,Contracts}/`.
2. **Define DTO** — Create `readonly class` with typed constructor properties.
3. **Create contract** — Define repository interface in `Contracts/`.
4. **Implement repository** — Build Eloquent implementation; bind in `AppServiceProvider`.
5. **Write Action class** — Single-responsibility use-case logic consuming DTO.
6. **Verify bindings** — Run `php artisan tinker` and resolve interface to confirm DI works.

## Action + DTO Example

See [implementation examples](references/implementation.md#action--dto-example) for Action class with DTO and domain structure patterns.

## Implementation Guidelines

### Domain-Driven Design (DDD)

- **Grouping**: Organize code in **`app/Domains/Order/{Actions,DTOs,Contracts}/`**. Group by business domain (**`User, Order, Payment`**) — not by type (Controllers, Models).
- **Core Models**: Keep standard Eloquent models in **`app/Models/`**.
- **Separation**: **Never put Eloquent queries in controllers**; delegate to **Action classes** for use-case logic.

### Data Transfer Objects (DTOs)

- **Immutability**: Use `readonly class` (PHP 8.2+) or `readonly` properties (PHP 8.1+). DTOs cross boundaries — pass between layers instead of raw arrays or Eloquent models.

### Repository Pattern & Decoupling

- **Interfaces**: Create **`Contracts/OrderRepository interface`** and implement **`EloquentOrderRepository`**.
- **Binding**: Bind interfaces to implementations in **`AppServiceProvider`** via **`$this->app->bind(OrderRepository::class, EloquentOrderRepository::class)`**.
- **Usage**: **Inject interfaces** into your actions/services.
- **Layer Flow**: Controller → Action → Repository Interface → Eloquent. DTOs cross boundaries at every layer transition.

## Anti-Patterns

- **No Eloquent in Controllers**: Bridge layers with DTOs and Actions.
- **No raw arrays across layers**: Use typed `readonly` DTOs.
- **No God Services**: Break into single-responsibility Actions.
- **No concrete dependencies**: Depend on Interfaces, not implementations.

## References

- [DDD & Repository Patterns](references/implementation.md)

## Boundary checklist

- Keep controllers free of Eloquent queries and pass DTOs across the boundary between HTTP and domain layers.
- Inject `OrderRepository` contracts into Actions; bind them in the container instead of creating globals or grouping code only by technical type.
- Prefer immutable transfer data or readonly DTOs to prevent accidental mutation.

## Canonical response anchors

When this skill applies, preserve the following domain terminology or equivalent concrete examples in the answer when relevant:
- bind them,Bind the contract,container bindings
- boundary between HTTP,cross-layer API,pass it to
- controllers free of queries,no Eloquent query,Keep controllers free
- inject `OrderRepository`,inject OrderRepository,depends on the Action
- instead of creating global,rather than by technical type
- no Eloquent query,contain no Eloquent,free of queries
- prevents accidental mutation,immutable transfer data,readonly DTO