Retrive Laravel Package

Getting Started

atannex/retrive is a data-retrieval layer that sits on top of Eloquent. Instead of scattering query scopes, when() clauses, and with() calls across controllers, you describe what a resource exposes once and let the package resolve the query. Install it and confirm the platform requirements first — PHP 8.3+ and Laravel 11 or 12 only. On older stacks, stop here; there is no backport path.

composer require atannex/retrive

Then, in order:

1. Read the README's setup section before writing code. The package needs a resource definition per model and, most likely, a config file. Publish the config (php artisan vendor:publish) and check whether caching is enabled by default — that is the setting that will surprise you first in local development.
2. Define one resource for a model you already query heavily — a Post or Product. The resource is where you declare filterable attributes, sortable fields, allowed includes, and visibility rules. This is the single file you will return to most often, so treat it as the source of truth for the resource's public surface.
3. Make your first retrieval through the fluent retriever rather than a raw Eloquent chain, e.g. Post::retrieve()->filter(...)->sort(...)->include(...)->get(). Verify method names against the README — the retriever's fluent surface is the part most likely to shift between minor versions.

The first genuinely valuable use case is a listing endpoint: an index action with request-driven filters, sorts, pagination, and eager-loaded relations. Replacing hand-rolled $request->query('sort') branching with a declared resource is where the package earns its place. Start there, not with the exotic features (neighbours, related records) until the basic listing path is clean.

Magic finders (getPostBySlug, getPostsByCategory) are the lowest-effort win — they give you typed conveniences that read well in controllers and can be adopted incrementally, one call site at a time.

Implementation Patterns

Resource-first, then retrieve. The package's core discipline is that the model stays thin and the resource declares the contract: which columns are filterable, which are sortable, which relations are includable, and who can see what. Resist the urge to also keep hand-written scopes doing the same job — duplicated sources of truth are how visibility bugs appear.

Request-driven filters as the default for index endpoints. The intended pattern is to pass the request through to the retriever and let the resource's declarations act as an allowlist. This is the package's biggest ergonomic gain and its biggest trust boundary: the resource declaration is your input validation. Be explicit about it, and add feature tests that assert an unexpected query parameter is ignored rather than applied.

Visibility rules belong in the resource, not the controller. Anything like "drafts only visible to authors and editors," "prices hidden for guests," or "soft-deleted rows excluded except for admins" should be declared once. Be careful that magic finders honour those rules — verify this with a test, because a convenient finder that bypasses visibility is the worst possible footgun.

Compose the fluent chain, but keep it shallow. A retrieval chain of filter → sort → include → search is readable; a twelve-call chain spread across a controller, a service, and a middleware is not. If a chain grows, wrap it in a named method on the resource or a small application-level query object, so the intent survives.

Caching is self-invalidating — so lean on it, and test it. The promise here is that cached retrieval results are invalidated when the underlying models change. Use it for read-heavy listing pages and search results, but write one integration test per resource that (a) retrieves, (b) mutates the model, (c) retrieves again and asserts freshness. This is the single most important test class for a package that owns your cache keys, because a silent staleness bug is nearly invisible in development.

Hierarchy-aware relation filters are for trees, not general filtering. If you have categories, folders, org units, or comments with parent/child structure, use the hierarchy filters rather than hand-rolling recursive CTE logic. Keep the recursion scoped to genuinely finite trees and add a depth cap in your resource if the data model permits pathological nesting.

Neighbours and related records are for detail pages. "Previous/next post," "other products in this collection," "similar articles" are the intended consumers. These are usually the last features you adopt and the ones most likely to need caching, since they tend to fire on your highest-traffic pages.

Integrate at the boundary you already have. For an API, the retriever's output can feed your existing API Resource / transformer classes — don't let the package dictate your response shape. For Blade-rendered pages, use the retriever for the data and keep pagination rendering in the framework's standard paginator.

Gotchas and Tips

• Platform floor is hard. PHP 8.3 and Laravel 11–12 mean this package will not install on a Laravel 10 application. Check composer why-not before promising it to a legacy codebase; the constraint may cascade into your other dependencies.
• v1.0.0 is the first stable release. The API is now something you can build against, but expect the README to be the authoritative reference — earlier 0.x usage examples circulating online may not match.
• Magic finders are magic. They rely on convention-based resolution of names like getPostsByCategory. Expect occasional guesswork about pluralisation, nesting, and argument order, and expect naming collisions with your own model methods. Prefer explicit retriever calls in code that other people will maintain, and treat finders as sugar for straightforward cases.
• Request-driven means user-driven. Any parameter the retriever accepts is attack surface: unsortable-column errors, expensive includes, unbounded search. Confirm the resource allowlist behaviour with tests, and cap pagination size at the controller or config level.
• Includes cause N+1s if not actually eager-loaded. Verify with DB::listen or Laravel Telescope that an include('comments.user') produces two queries, not N+1. A retrieval layer that names relations is not the same as one that eager-loads them correctly.
• Cache invalidation is invisible until it's wrong. Queue workers, updateQuietly(), DB::table() bulk updates, and raw SQL all bypass Eloquent model events and therefore may bypass invalidation. If you mutate outside Eloquent, assume the cache is stale and invalidate manually or clear on deploy.
• Per-user visibility plus a shared cache is a classic trap. If visibility rules change the result set by user or role, the cache key must include that dimension. Test as two different users back-to-back; a cache keyed only on the resource and filters will happily serve an admin's results to a guest.
• Search needs database support. Full-text-ish search backed by LIKE '%term%' will not scale and will not use indexes. Check what the package generates (toSql() on the retrieval, or Telescope) and add appropriate indexes — or a real search driver — before shipping to production.
• Hierarchy filters can be expensive. Recursive queries on deep trees are the usual cause of slow listing pages. Log the generated SQL for one hierarchy-filtered request and confirm it's a single query rather than a loop.
• Config quirks around caching in development. Stale cached results during local iteration look like bugs in your code. Keep caching off (or use a null/array store) locally, and always clear cache after changing a resource definition — resource declarations feed cache keys, and a key mismatch is a confusing failure mode.
• Extension points to prefer. When the package's defaults don't fit, extend at the resource definition and the retriever chain first; reach for overriding package internals only after checking whether a config or resource-level hook exists. Subclassing internals is the fastest route to a painful upgrade.
• Pin the version and read the changelog on upgrade. For a young package owning query construction and caching, treat minor bumps as reviewable changes; a one-line changelog entry can alter query semantics across every endpoint at once.