Retrive Laravel Package

Product Decisions This Supports

• Build vs. buy for the read path. Most CRUD-heavy products eventually grow a hand-rolled "repository + filters + includes + cache" layer in controllers and form requests. This package is a direct buy signal for that layer: resource definitions, a fluent retriever, request-driven filters/sorts/includes, search, and caching in one dependency. The decision to evaluate is not "do we need this?" (you almost certainly already built a worse version of it) but "do we adopt a third-party abstraction for it?" Frame it as a replace/standardise decision, not a net-new feature.
• API surface consistency as a roadmap enabler. Request-driven filters, sorts, and includes mean new list endpoints ship as configuration rather than bespoke query code. That compresses the cost of adding endpoints to existing resources — a meaningful input when prioritising a public/partner API, admin console, or mobile client against other roadmap items.
• Time-to-market on content-shaped features. The magic finders (getPostBySlug, getPostsByCategory) are a strong fit for CMS, catalogue, publishing, and directory-style products. For teams whose backlog is full of "add a filtered listing page / detail lookup / related-items rail," this is measurable cycle-time reduction and should be scored as such in prioritisation, not dismissed as "just a library."
• Performance work without a caching project. Self-invalidating caching converts "we should really add caching to the read endpoints" from a multi-sprint platform initiative into a per-resource configuration task. That changes the cost side of a performance roadmap item and may let you defer or cancel a dedicated caching epic.
• Search and discovery features move from "later" to "now." Built-in search plus neighbours and related records makes recommendation-adjacent and "more like this" features cheap enough to include in an MVP rather than deferring them post-launch.
• Visibility rules are a product-policy question, not only a technical one. A declarative visibility layer invites product to define who sees what in one place. Decide explicitly whether this becomes your source of truth for read visibility or stays a presentation convenience layered under Laravel policies — that ownership question should be settled before adoption, not after.
• Forces an upgrade conversation. PHP 8.3+ and Laravel 11–12 constraints make adoption contingent on your platform baseline. Treat it as a data point in the "when do we move off Laravel 10" decision rather than an isolated dependency choice.

When to Consider This Package

Consider adoption when most of the following hold:

• You have (or are about to have) many read endpoints over Eloquent models — public API, admin panel, mobile backend — and each currently carries bespoke filtering/sorting/pagination code.
• Your domain is content- or catalogue-shaped: slugs, categories, taxonomies, hierarchies, related items, search. The magic-finder and hierarchy-filter features pay off in proportion to how much of your model graph is navigational.
• Your baseline is PHP 8.3+ and Laravel 11 or 12, or you are already planning that upgrade.
• You have a repeatable caching pain point — stale read data, manual cache-busting bugs, or a deferred caching epic — and want invalidation handled at the model layer.
• You can accept a convention-driven API: magic finders imply string/convention-based resolution, which is fast to write and slower to debug, harder to statically analyse, and less discoverable for new engineers. Teams with strong IDE/static-analysis cultures should weigh this deliberately.
• You are willing to spike before committing: a one-to-two-day proof on your two most complex read endpoints, including one with non-trivial visibility rules and one hierarchical relation, is the right gate.

Look elsewhere when:

• Your read layer is small or bespoke — a handful of endpoints where the abstraction costs more to learn than it saves.
• You need guaranteed long-term support, a vendor SLA, or an active multi-maintainer team. This is a v1.0.0 first stable release; maturity, contributor depth, and release cadence are unproven. That is a legitimate reason to defer to a later minor version, not a reason to reject outright.
• You are on Laravel 10 or earlier, or PHP below 8.3, and cannot move.
• Your visibility requirements are regulatory or audit-sensitive. Read-visibility rules defined in a young third-party package should not be your only control; verify how it composes with Laravel policies and gates before trusting it.
• Your architecture is write-heavy or event-driven — this addresses the read path, so it will not move the metrics you care about.

How to Pitch It (Stakeholders)

To executives: This is a small, low-cost dependency that standardises how our application reads data from the database. It replaces code we would otherwise hand-write and maintain, standardises filtering/sorting/search across our endpoints, and adds caching with automatic invalidation — which means faster pages and fewer stale-data bugs without a dedicated performance project. The trade-off is maturity: it is a first stable release (v1.0.0) from a single package, requiring PHP 8.3+ and Laravel 11+. Recommendation: fund a short, time-boxed spike on two real endpoints and revisit at the next minor release, rather than committing broadly on v1.0.0.

To engineering: Scope covers resource definitions, a fluent retriever, magic finders, request-driven filters/sorts/includes, visibility rules, hierarchy-aware relation filters, search, neighbours, related records, and self-invalidating caching. It sits directly on Eloquent, so blast radius is contained and removal is tractable if we keep usage behind a thin boundary. Two things to pressure-test in the spike: (1) debuggability and static-analysis ergonomics of the convention-based finders, and (2) how its visibility rules interact with existing policies and gates — we must not end up with two competing answers to "can this user see this row." Also confirm the PHP 8.3 / Laravel 11–12 requirement aligns with our upgrade plan.

Decision requested: approve a time-boxed evaluation spike plus an ADR recording the outcome; do not adopt as a platform standard until the spike clears and the package shows a second release with responsive maintenance.