Jsonapi Rql Finder Bundle Laravel Package

Product Decisions This Supports

• API capability roadmap: whether to expose expressive, RQL-style filtering (filter=eq(status,active)&sort=-created_at) on our JSON:API endpoints, versus shipping another round of bespoke query params. RQL gives consumers a familiar, composable syntax instead of us inventing one per endpoint.
• Build vs. buy on the query layer: this package is a thin translation layer between RQL and the paknahad/jsonapi-bundle query builder. Adopting it defers ~1–2 sprints of work; the decision it really forces is "do we own this forever, or write our own 500-line filter adapter?" The 3.0.0 release marginally strengthens the "buy/borrow" side — it clears the PHP 8 blocker — but does not change the ownership math.
• Use cases it unlocks: back-office/admin SPA filtering over many resources, partner integrations that need compound filters (AND/OR, nested), and a migration path from ad-hoc ?status=active params to a documented, versioned filter contract.
• Specification input, even if we don't adopt: reading its operator mapping is cheap and tells us exactly what a filtering DSL contract must define — operator set, nesting limits, sort semantics, pagination interaction, field allowlisting. Useful as acceptance criteria for an in-house build.
• Security posture decisions: an RQL surface is a new attack surface (unbounded nesting, field enumeration, expensive queries). Evaluating this package forces an explicit decision on query-complexity limits and per-resource field allowlists.
• Dependency-risk precedent: a 3.0.0 major bump carrying a single line — "Support for PHP 8" — is itself a data point about release-management rigor. That's a policy signal (how much do we trust this maintainer's semver discipline?) as much as a technical one.

When to Consider This Package

Consider only if all of these hold:

• We are already committed to paknahad/jsonapi-bundle (Laravel JSON:API implementation) and don't want to hand-roll filtering on top of it.
• Filtering needs are read-only and moderate in complexity; consumers are few and known.
• We can pin the version, vendor the source, and accept owning maintenance ourselves — the surface is small enough to audit in an afternoon.
• New: We verify the PHP constraint actually covers our runtime (see below) rather than trusting the changelog line.

Look elsewhere (or build) when:

• Maintenance signal is still the blocker. 7 stars, 0 dependents, and a ~3-year gap between the last release (March 2022) and 3.0.0 — a single changelog line, no security policy, no dependent projects to signal real-world use. The 3.0.0 tag shows the maintainer is not fully gone, but it is a pulse, not a heartbeat. We would still be the only real user.
• "Support for PHP 8" is not a compatibility claim we can act on. It does not specify 8.0 vs. 8.2/8.3, says nothing about Laravel 10/11, and the major version bump implies breaking changes it never documents. Treat this as unverified until we read composer.json and run the suite on our actual runtime. Risk downgraded from "expect friction" to "unknown — cheap to check."
• Framework ambiguity. The package name says "bundle" (Symfony convention) while its target, paknahad/jsonapi-bundle, is a Laravel package. Verify the service-provider registration path before assuming it drops into a Laravel app cleanly — the 3.0.0 major bump could have changed exactly this.
• Better alternatives: implement a thin Eloquent/Query Builder filter adapter ourselves (small, fully controlled); use a maintained RQL parser library with our own adapter; or stick to the JSON:API standard filter[...] convention plus a whitelist if consumers don't need nested boolean logic. If consumers need genuinely expressive querying, that's a GraphQL conversation, not this.
• Mandatory diligence if we proceed: read the 3.0.0 diff and composer.json constraints, smoke-test on PHP 8.2/8.3 + our Laravel version, operator/field allowlist, max nesting depth, query cost limits, test coverage audit, and a documented exit plan.

How to Pitch It (Stakeholders)

Executives: "There's an off-the-shelf filter syntax for our API — MIT-licensed, small, but essentially unused: 7 stars, zero dependent projects. It was dormant since 2022 and just shipped a major version whose entire changelog is 'Support for PHP 8.' That's a positive signal — it removes the reason we'd previously have to fork — but it's a single line after three years, and a major version bump implies breaking changes nobody documented. My recommendation is unchanged: don't take it as a production dependency yet. Use it as a design reference and budget roughly 1–2 sprints for a small in-house filter layer we fully control, or a maintained parser with our own adapter. The one thing that changed: the compatibility objection is now unverified rather than known-bad, so a few hours of diligence could legitimately reopen the adopt option. That check is cheap — I'd spend it before we commit the sprints."

Engineering: "3.0.0 is a one-line release: 'Support for PHP 8.' Read it as the PHP 8 blocker may be gone, not as this works on our stack. Before anything else: diff 3.0.0 against the 2022 release, read the composer.json PHP and Laravel constraints, and run the suite on PHP 8.2/8.3 with our Laravel version. A 3.0.0 bump for a PHP-version change likely carries real breaking changes to the service provider or operator mapping — the fact that they're undocumented is itself a maintenance-quality signal. Unchanged risks: zero dependents, no security policy, a new query surface needing an operator allowlist, field allowlisting, nesting-depth caps, and query-cost limits. If — and only if — the compat check passes and the diff is small, then: pin the version, vendor the source, and land the guards in the same PR, not later."