Repository Pattern

When to use

• The user wants domain code to save and load aggregates through an interface instead of writing SQL or ORM calls inline.
• The user needs to change the data store or query technology without touching the code that uses the data.
• The user wants to test business logic against an in-memory repository instead of a real database.

When NOT to use

• Do not wrap ad-hoc reporting or analytics queries that return raw rows in a repository when there is no aggregate to reconstitute.
• Do not add repositories to a small CRUD app that deliberately uses active-record models and has no separate domain layer.

Core guidance

• Give the repository collection-like methods — Shape the interface like an in-memory collection of aggregates — add, remove, findById, matching(criteria) — rather than exposing raw query builders.
• Define the repository interface in the domain — Declare the repository as an interface that lives in the domain layer and is expressed in domain terms; keep the concrete implementation in infrastructure.

Quick recipe

1. Declare an interface per aggregate in the domain with collection-like methods, e.g. interface CustomerRepository with add(Customer $c): void and ofId(CustomerId $id): ?Customer. (verify: The interface names domain operations and mentions no ORM or SQL type)
2. Write a concrete implementation in infrastructure that maps rows to aggregates, e.g. EloquentCustomerRepository implements CustomerRepository, keeping all query building inside it. (verify: The implementation returns reconstituted aggregates, never raw rows or a query builder)
3. Bind the interface to the concrete repository at the composition root, and add an in-memory implementation for tests that stores aggregates in an array. (verify: A use-case test runs against the in-memory repository with no database)

Best practices

• Encapsulate each meaningful query behind a named method (findActiveByCustomer) or a specification, instead of letting callers assemble WHERE clauses
• Provide one repository per aggregate root and load or store the whole aggregate through it, rather than a repository per table
• Have the repository return fully reconstituted domain objects (or null / a not-found result), never raw rows, arrays, or ORM result sets

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. A god repository with dozens of finders — Letting one repository accumulate every query the app ever needs produces a bloated interface that mixes unrelated concerns. Fix: Keep the repository scoped to its aggregate's core lifecycle, and move complex read-side queries into dedicated read models or query services.
2. Returning a query builder from the repository — Exposing a method that returns the ORM query builder lets callers append arbitrary clauses, dragging query construction back out of the repository. Fix: Return finished domain objects or collections from named methods, and keep all query building inside the repository implementation.
3. N+1 queries hidden behind the interface — A repository that lazily loads each related aggregate on access can fire one query per item, turning a list load into an N+1 storm the caller cannot see. Fix: Add a method that eager-loads the needed relations in one query, and measure query counts in a test so regressions surface.

Version notes

• Readonly identifiers strengthen lookups in PHP 8.1 (PHP >=8.1) — PHP 8.1 readonly properties let identifier value objects (a CustomerId) be immutable, so repository lookup methods can take a typed id instead of a bare int or string.
• Native lazy objects aid hydration in PHP 8.4 (PHP >=8.4) — From PHP 8.4, native lazy objects let a repository return a placeholder aggregate that hydrates on first use, deferring the database read without a hand-rolled proxy.

Security

• Not applicable — no I/O, auth, or untrusted input.

Testing

• Activation and decision behavior are verified in eval/scenarios/architecture/repository-pattern.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Prerequisites: architecture/hexagonal
Related: architecture/service-layer, php/value-objects