Laravel Api Toolkit Laravel Package

Product Decisions This Supports

• Multi-tenant and permission-scoped data exposure: v1.16.5 fixes a query-filter flaw where an $or group could escape a caller's scope. For any product where row-level visibility matters (tenant isolation, per-customer data, role-based visibility, soft-deleted or draft records), this moves the package from "convenience layer" to "correctness-critical dependency." It directly supports decisions about whether client-supplied filter syntax is safe to expose in public or partner-facing APIs.
• Build vs. buy for API plumbing: The package covers request-driven filtering, sorting, pagination, and inclusion of related resources — the boilerplate most CRUD APIs rewrite per project. This release reinforces the "buy" case on capability, but adds a maintenance obligation: you now inherit upstream security posture, so the decision should include a patch-velocity check, not just a feature check.
• Roadmap sequencing for public API / integration surfaces: If filtered list endpoints are on the roadmap (partner API, embeddable widgets, admin consoles with saved views), adopt the package before writing bespoke filter parsers. If they are not, this is premature.
• Authorization architecture: The fix implies the intended contract is "caller applies a scope, filter input cannot widen it." That is a product-level security invariant worth writing into the API spec and test suite, regardless of whether you use this package — it also gives a concrete acceptance test for any homegrown equivalent.
• Upgrade and dependency policy: A patch-level version (v1.16.5) containing a security-relevant fix is a signal to adopt auto-applying patch updates with a tested rollback path rather than quarterly dependency sweeps, at least for packages that touch query construction.
• Use cases well served: internal admin tooling, SaaS back-office endpoints, mobile app backends over Eloquent, and any Laravel product where the team wants a documented filter grammar instead of ad hoc request()->get() parsing.
• Not a differentiator: This is infrastructure. It removes risk and toil; it does not create user-visible value. Fund it from engineering hygiene budget, not from a product bet.

When to Consider This Package

Consider adoption when all of the following hold:

• The stack is Laravel with Eloquent as the primary data access layer; the package's value collapses quickly outside that context.
• You are exposing — or about to expose — list endpoints with client-chosen filtering, sorting, or pagination, and you would otherwise hand-roll that parsing.
• You can enforce scoping at the call site (global scopes, tenancy middleware, explicit query scopes). The v1.16.5 fix protects a properly scoped caller; it does not substitute for applying the scope in the first place. Treat "do we reliably scope every list query?" as a prerequisite, not an outcome.
• Your team accepts taking regular patch updates, ideally automated, and has CI that exercises filtered endpoints.
• You want a stable, documented filter grammar shared across services rather than each team inventing one.

Look elsewhere, or build narrowly yourself, when:

• Query construction is simple and static — a handful of fixed filters do not justify a dependency that sits on the authorization boundary.
• You need a hardened, independently assessed query language for untrusted public input. A community package with a security fix history in exactly this area is a reasonable choice, but if the exposure is sensitive enough to warrant threat modeling, own the parser or constrain input to a server-defined whitelist of filterable fields.
• The data layer is not Eloquent, or you are using an ORM/query builder abstraction where the package's assumptions break.
• You cannot pin and audit versions (locked-down release process, regulated environments requiring vendor review) — the absence of a formal security disclosure process means you cannot get ahead of issues like this one.
• You are already satisfied with an established alternative (e.g., a mature filter/sort package or Spatie/Laravel Query Builder) — the marginal gain does not justify migration.

Adoption guidance introduced by this release: pin to ^1.16.5 or later, add a regression test that asserts an $or filter cannot return rows outside the caller's scope, and prefer whitelisting filterable fields and relations over accepting arbitrary keys from the client.

How to Pitch It (Stakeholders)

For executives (one paragraph): We evaluated a Laravel package that standardizes how our APIs accept filtering, sorting, and pagination from clients — work we currently repeat in every service. Its latest release fixes a filter-grouping bug where a crafted $or condition could step outside the scope the calling code applied, which is exactly the kind of defect that causes cross-customer data exposure. The fix is a low-risk patch, and it tells us two useful things: the maintainer treats scope containment as a genuine security boundary, and we must stay current on patch releases for components that build database queries. Recommendation: adopt it for list endpoints where we already scope queries correctly, pin to the fixed version or later, and add an automated test that proves customer data cannot leak through filter input. Cost is a dependency plus a small amount of CI work; the alternative is writing and securing this logic ourselves in every project.

For engineering leads (summary):

• What it is: request-to-Eloquent query layer — filters, sorts, pagination, relation includes — with a defined input grammar instead of hand-parsed query params.
• What changed: v1.16.5 groups filter criteria so an $or group cannot escape the caller's scope. Patch version, no API changes, no deprecations, no migration steps.
• Why it matters: the package sits on the authorization boundary. A scope escape is a data-isolation bug, not a cosmetic one. Our existing scoping discipline is necessary but was not, on its own, sufficient against this class of input.
• Actions:
  1. Pin ^1.16.5; if already on 1.16.x, schedule the patch in the next deploy cycle rather than the next dependency sweep.
  2. Whitelist filterable fields and relations per endpoint; do not forward raw client keys.
  3. Add a regression test: apply a tenant/user scope, submit an $or filter attempting to reach outside it, assert zero out-of-scope rows.
  4. Audit any endpoint that accepts nested or grouped filter syntax for the same invariant — including places where we build queries by hand.
• Risks to track: single-maintainer project; no formal security advisory channel, so we learn about fixes from release notes — automate dependency notifications and keep the upgrade path frictionless.
• Not recommended if our list endpoints use a fixed set of server-defined filters, or if release governance prevents us from following patch updates.