laravel-patterns

Laravel Patterns

Placement rules for domain-driven Laravel applications: Action, Service, Repository, Query Class, Value Object. 63 rules across 9 sections.

Core philosophy: practicality over purity. Never take a greedy decision.

• Eloquent is already a good abstraction for most data access.
• A Repository over Eloquent does not fully decouple you from Eloquent. That is acceptable and expected — do not chase purity.
• Both extremes are bugs: a layer for every model (dead boilerplate) and none at all (queries scattered everywhere).
• A Query Class is the internal implementation technique of a Repository, not a competing pattern.
• Value Objects keep signatures clean and carry pure behavior. They never touch a Builder.
• Domains are bounded contexts. One domain never imports another's internals.

When to Apply

Reference these rules when:

• Creating any class under app/Domain/
• Deciding between a Service, a Repository and inline code
• Reviewing a pull request that adds a layer
• Refactoring queries scattered across Actions, Services or Blade
• Splitting a monolithic app/ into bounded contexts
• Wiring one domain to another

Start Here

Run the Decision Gate before writing any class: references/decision-gate.md.

Default answer: keep it in the Action, use Eloquent directly.

Q1. Single end-to-end use case?              → ACTION
Q2. Called by 2+ Actions, or worth isolating? → SERVICE
Q3. Used in only one Action?                  → KEEP IT IN THE ACTION
Q4. Single-record CRUD (find / create /
    update / delete)?                         → ELOQUENT DIRECTLY
                                                (from an Action or Repository)
Q5. Backend may swap, OR the query earns a
    name and its own tests?                   → REPOSITORY (+ Query Classes)
Q6. Two real implementations, a concrete
    backend swap, or a host extension point?  → INTERFACE
                                                (otherwise one concrete class)
Q7. Callers pick one by a config or
    request key?                              → FACTORY / REGISTRY