L5 Repository Laravel Package

Product Decisions This Supports

• Build vs. buy for the data-access layer. Decides whether to hand-roll a repository/query-object layer (2–4 sprints of design, review, and documentation) or adopt an established, MIT-licensed implementation with criteria, presenters, caching, and validation baked in. This package makes “buy” cheap enough to trial in a single bounded context before committing.
• Architecture direction: Eloquent-coupled vs. abstracted persistence. Informs whether the roadmap can absorb a future data-store change (read replicas, search index, legacy DB alongside the new one, multi-tenant sharding) without rewriting controllers and services. Repositories create a seam that turns a quarter-long migration into a bounded workstream.
• Feature roadmap for complex query surfaces. Criteria (composable, named query filters) and presenters (output transformation) directly enable admin filter panels, public API response shaping, and per-endpoint caching without duplicating query logic across controllers — useful when scoping “advanced search” or “API v2” epics.
• Testability and CI investment. Repository interfaces let teams mock persistence in unit tests and reserve database hits for integration tests. This is a lever on test-suite runtime and flakiness — a real input to delivery-velocity planning.
• Team scaling and ownership boundaries. If multiple squads touch the same domain, a repository contract is a governance artifact: it defines who owns query logic and prevents controllers from reaching into the ORM. Supports a modular-monolith or DDD-lite split without a full framework migration.
• Technical-debt triage. Where query logic is already smeared across controllers, this quantifies a remediation path (extract to repositories incrementally, criteria by criteria) rather than a big-bang refactor.
• Caching strategy decisions. Built-in repository caching lets the team decide “cache at the data layer” vs. “cache at the edge/service layer” with an implementation already available, shortening the time to a decision.
• Vendor-lock-in risk register. A persistence seam is a hedge; this package is a low-cost way to book that hedge without committing to a heavier ORM (Doctrine) or a bespoke abstraction.

When to Consider This Package

Adopt or spike when:

• The codebase is a Laravel application of meaningful size (roughly 30+ models or multiple teams) where query logic is already duplicated across controllers, jobs, and console commands.
• You have a credible, dated roadmap trigger for persistence change or added read paths — read replicas, a search engine, a reporting DB, a legacy system integration, or multi-tenant partitioning.
• Your API surface needs consistent, composable filtering and response shaping (criteria + presenters) that would otherwise be reimplemented per endpoint.
• Test speed and isolation is a named bottleneck; mocking repositories is materially cheaper than database-backed tests.
• You want a standard pattern for onboarding — new engineers read one base class and one contract instead of reverse-engineering ad-hoc Eloquent usage.
• You are willing to own a fork if necessary; MIT licensing makes that a viable fallback rather than a blocker.

Look elsewhere when:

• The app is small or CRUD-dominated (fewer than ~15 models, one team). The abstraction cost — extra indirection, more files per feature, indirection in stack traces — exceeds the benefit; Eloquent scopes and query objects cover it.
• The team is not aligned on the repository pattern or has had a bad prior experience with anaemic, one-method-per-query repositories. Without a convention, this package accelerates the anti-pattern.
• You need framework-agnostic or non-Eloquent persistence (Doctrine, event-sourced, raw SQL-heavy analytics). This package is explicitly Eloquent-shaped; it is not a true persistence-agnostic boundary.
• Performance-critical, high-QPS paths where the extra layer and criteria resolution add measurable overhead and obscure generated SQL. Benchmark before adopting on hot endpoints.
• Long-horizon platform bets on current Laravel. The project’s “Laravel 5” framing and low opportunity signal (29/100) hint at diminishing differentiation versus modern Laravel idioms; if you are on a recent major version, validate compatibility, maintenance cadence, and issue responsiveness with a real spike first.
• Zero-dependency or strict supply-chain postures — you will be adding a transitive surface you must track; the reported dependent count is not a reliable proxy for ecosystem health, so treat maintenance risk as an open item.
• You are pursuing full DDD with a separate domain model. Repositories returning Eloquent models leak the ORM into the domain; that requires a mapping layer this package does not provide.

How to Pitch It (Stakeholders)

To executives (one paragraph): We are evaluating a small, MIT-licensed library that puts a thin, standard interface between our application code and the database. The business case is optionality and speed: it lets us add filtering, caching, and API response shaping once instead of per feature, makes our tests faster and less brittle, and — most importantly — means that if we later need to change how or where data is stored (replicas, search, a legacy system), we change it in one place rather than across the product. Cost is low: no licence fee, an incremental adoption path scoped to one module, and a deliberate exit ramp because we can fork it. Recommended next step is a two-week, single-module spike with explicit success criteria (feature cycle time, test runtime, query-log review) before any org-wide standard.

To engineering (summary): plum/l5-repository gives us BaseRepository, composable criteria, presenters, a caching hook, and validator integration on top of Eloquent. Adopt it as a convention, not a religion: one repository per aggregate, criteria for reusable filters, presenters only where output shape differs from the model. Guardrails we should commit to up front — no passing query builders out of repositories, no one-method-per-query repositories, no repository calls from within criteria, and an explicit rule that hot paths get benchmarked and may bypass the layer. Risks to close during the spike: compatibility with our Laravel version, maintenance cadence, and the fact that this is an Eloquent-shaped abstraction — it does not give us a true persistence-agnostic domain boundary, so we should not sell it internally as one. Success looks like: duplicate query logic removed from at least three call sites, unit tests running without a database for the affected module, and no regression in p95 latency on the endpoints we convert.