introducing-repository ยท diff
git:20260922.00e7bbe to git:20260922.7ecf42a
7 added, 18 removed. Audit A to A.
---
name: introducing-repository
- description: Introduce a repository only when persistence needs a meaningful abstraction beyond direct Eloquent usage.
+ description: Evaluate, introduce, or refactor persistence abstractions when direct Eloquent is insufficient. Use for repository requests, complex aggregate reconstruction, or multiple persistence implementations; reject CRUD wrappers without a concrete benefit.
---
- # Introducing a Repository
-
- Direct Eloquent usage is the default.
-
- Do not introduce repositories merely because the application uses DDD.
-
- Introduce a repository only when it solves a concrete problem, such as:
+ # Repositories only when needed
- - a meaningful persistence boundary
- - multiple persistence implementations
- - complex aggregate reconstruction
- - persistence details that should be hidden from Domain/Application code
+ Direct Eloquent is the default in Domain and Application. Loading an order and calling `$order->save()` from `CancelOrder` does not require a repository, interface, or separate persistence entity.
- Do not create:
+ Introduce a repository only for an actual persistence problem, such as complex aggregate reconstruction, multiple implementations, or a meaningful boundary hiding specialized storage.
- RepositoryInterface
- EloquentRepository
- Repository
+ When the implementation lives in Infrastructure, put the contract with its consumer in `App\Domain\<Capability>\Contracts` or `App\Application\<Capability>\Contracts`. Infrastructure implements it; a Laravel service provider binds it. The consumer receives the contract rather than the concrete implementation.
- as ceremony around simple Eloquent queries.
+ Name the contract for the capability it provides and use consumer-owned types in its API. Avoid generic `RepositoryInterface`, `BaseRepository`, or CRUD forwarding methods around Eloquent. Do not introduce a repository solely to mock a model in an Action test.
- When direct Eloquent usage is clear and maintainable, prefer it.
+ Keep transaction coordination in the Action. A repository should not silently commit the caller's unit of work. Reusing an existing suitable abstraction is preferable to building a parallel one.