Jsonapi Rql Finder Bundle Laravel Package

Technical Evaluation

Architecture fit

• Unchanged in substance. The package name and packaging (...-bundle, README reference to paknahad/jsonapi-bundle) still indicate a Symfony bundle, not a Laravel package. It occupies the query-translation layer between an HTTP request and the persistence layer: it takes an RQL expression and produces a Doctrine query/finder result for the parent JSON:API bundle's resource pipeline.
• If our stack is Laravel, this remains an architectural mismatch. Laravel's JSON:API implementations (laravel-json-api, cloudcreativity/json-api) use service providers, Eloquent scopes, and their own filter/sort handling — none of which this bundle targets. Adopting it in Laravel would mean forking and re-hosting the RQL parsing logic behind Eloquent, not installing it.
• If our stack is Symfony and we are already on paknahad/jsonapi-bundle, fit is good and the integration surface is small — likely a bundle registration plus a service definition wiring the finder into the existing finder interface.
• New in this release: the 3.0.2 artifact is published from Krilo89/jsonapi-rql-finder-bundle, not the paknahad namespace the earlier assessment referenced. Before anything else, confirm whether this is a repo transfer, a rename, or an independent fork, and which Composer package name the 3.0.x line ships under. If the vendor name changed, existing composer.json constraints referencing the old name will silently stop receiving updates.

Integration feasibility

• Still a small, single-purpose codebase: expected to be a handful of classes (RQL parser/tokenizer + a finder adapter + DI extension). Low lines-of-code means low cost to audit fully — a TPM should budget an actual read-through rather than relying on community signals, which remain absent.
• Hard prerequisite remains the paknahad/jsonapi-bundle dependency. That package is itself low-activity, which compounds risk — we would be inheriting a two-link chain of thinly maintained libraries. Verify the parent bundle is compatible with the 3.0.x line of this package; a major-version bump on the child is a plausible signal that the parent pin moved too.
• RQL is not part of the JSON:API specification. The spec standardizes filter[...], sort, include, page, and sparse fieldsets; RQL is a separate dialect (comparison operators, logical composition). Adopting it means generic JSON:API clients and generated SDKs will not speak our filter syntax, and we take on client-side documentation and tooling work.

Technical risk

• Abandonment risk: revised from high to moderate. The prior finding was anchored on "last release 2022-05-09, no activity." That anchor is now wrong: a 3.0.x line exists and 3.0.2 shipped. This is a genuine positive signal — the project is not dead — but it is a weak signal. A single develop -> master merge with no changelog, no described fixes, and no compatibility statement tells us nothing about what was actually repaired or tested.
• Process/documentation risk: elevated, and now the dominant concern. The release notes contain zero substantive content — no breaking-change callout, no migration notes, no test or CI evidence. For a major version (3.x) that is a real gap: we cannot tell from the artifact what changed relative to the 2.x line the earlier assessment described. Budget time to diff 3.0.1...3.0.2 and to read the 3.0.0 tag/CHANGELOG before assuming backward compatibility.
• Cadence risk: sporadic, undocumented releases are harder to plan around than a cleanly dead dependency, because they create ambiguity about whether to wait for an upstream fix or fork. Assume no release will land when we need it.
• Supply-chain visibility: a low-adoption transitive dependency still surfaces in SCA/composer audit and SOC2-style vendor review. Expect to write an exception or a fork justification regardless of the 3.0.2 release.
• Correctness risk: unchanged and still the highest-severity technical item. RQL → query translation is the classic place for unparameterized predicates and unbounded query construction. Verify parameter binding and operator allowlisting before trusting it with untrusted input. Note that a major-version bump is not evidence this was fixed — confirm in the diff.

Key questions

1. Is the target application actually Symfony? If Laravel, the answer is still "port the parser, don't install the bundle," and the estimate changes materially.
2. What changed between 2.x and 3.0.0, and between 3.0.1 and 3.0.2? Is there a CHANGELOG or UPGRADE guide? If not, we must diff the tags ourselves before spiking.
3. Is Krilo89/jsonapi-rql-finder-bundle a transfer, a rename, or a fork of the paknahad project? What is the Composer package name, and does it declare a replace/provide for the old one?
4. Are we already committed to paknahad/jsonapi-bundle, and is that package actively maintained and compatible with this 3.0.x line? If not, this bundle has no home.
5. Does 3.0.x raise PHP/Symfony/Doctrine minimums? A major bump commonly does — check composer.json constraints against our runtime rather than assuming the 2022-era constraints still hold.
6. Does it implement the JSON:API filter[] convention, RQL, or both? Which do our API consumers actually need?
7. Is there any test suite, and does it cover operator precedence, malformed-input handling, and parameterization?
8. Who owns a fork if we adopt it? MIT permits vendoring; a TPM should secure that decision before, not after, it goes to production.

Integration Approach

Stack fit

• Symfony 5/6-era bundle, Doctrine-oriented, intended to sit inside paknahad/jsonapi-bundle's finder abstraction. Version 3.x may have moved these floors — validate before relying on the earlier characterization.
• Not viable as-is for Laravel. The realistic Laravel path is extraction: lift the RQL grammar/parser, discard the bundle plumbing, implement translation against Eloquent query builder, and wrap it in a service provider plus request-level validation.

Migration path

• Symfony + paknahad already in place: composer require, register the bundle in bundles.php, configure, and point the resource finder at it. Days, not weeks — but now add a version-selection step: confirm whether we take 3.0.2 or pin to the version previously assessed, and record why.
• Greenfield or Laravel: vendor the source into an internal namespace (Acme\JsonApiRql) under MIT, add our own tests, and treat it as first-party code. Budget 1–2 engineer-weeks including a parameterization and operator-allowlist review.
• Either way, insert an anti-corruption layer: our resources depend on a small internal QueryTranslator interface, not on this package directly. That keeps a future swap to the spec-native filter[] approach to a single adapter, and insulates us from vendor-name churn.

Compatibility

• Diff 3.0.1...3.0.2 and read the 3.0.0 release before any spike. A silent major bump is the single most likely source of surprise in this release.
• Validate composer.json constraints against our PHP and Symfony versions; do not assume the pre-2022-release constraints carried forward.
• Check the transitive chain: this package → paknahad/jsonapi-bundle → its own Doctrine/Symfony constraints. Pin transitive versions explicitly rather than floating.
• Confirm the JSON:API spec version implemented by the parent bundle; mismatches with client expectations surface as confusing 4xx/5xx behavior, not clean errors.

Sequencing

1. Confirm framework and existing JSON:API investment (decision gate — stop here if Laravel).
2. Establish provenance: package name, repo ownership, and the 2.x→3.0 changelog. This is new and comes before the spike.
3. Timeboxed 3-day spike: install 3.0.2 in a branch, run one real resource through an RQL query, capture the generated SQL and error behavior on malformed input.
4. Fork decision: vendor into our namespace, add CI, license header, and ownership in CODEOWNERS.
5. Build the internal adapter interface and contract tests around it.
6. Ship behind a feature flag on one low-traffic endpoint; expand only after query-cost telemetry is in place.

Operational Impact

Maintenance

• Treat as self-maintained from day one. 3.0.2 confirms the project is not frozen, but the absence of changelog detail means upstream is not a reliable source of upgrade guidance. Assign a named owner, vendor the code, and add it to the dependency-review agenda.
• Budget roughly a few days per year for PHP/Symfony upgrade compatibility — modest, but only if we own the fork. Without a fork, that cost becomes a blocker at the next major framework upgrade.
• Watch the upstream release feed rather than assuming abandonment. A future 3.0.x may be worth rebasing onto; a future 4.x major should trigger a re-review, not an automatic bump.

Support

• No vendor, no community, and — per the 3.0.2 notes — no meaningful release documentation. Support burden falls entirely on the adopting team; on-call must be able to read the parser.
• Expect procurement/security review friction: a low-adoption, thinly documented dependency still needs a documented risk acceptance with a remediation date, even though it is no longer accurately described as "no releases since 2022."

Scaling

• Query cost is the real scaling concern, not throughput. RQL permits composed logical filters; without guardrails a single client can generate expensive joins or unindexed scans.
• Enforce: maximum operator depth, allowlisted operators per resource, mandatory pagination, statement timeouts, and query-plan review for each exposed filterable field.
• Parser is pure CPU and cheap — horizontal scaling is not the issue; database contention from permissive filtering is.

Failure modes

• Malformed RQL surfacing as 500 instead of 400 — a client-experience and alerting-noise problem; wrap the parser in request validation.
• Unparameterized predicate construction → injection surface; audit before exposing to untrusted clients. Re-verify against 3.0.2 specifically, since no security content is described in the release.
• Silent behavioral change introduced by an unlogged patch release; contract tests on generated SQL are the mitigation, and pinning exact versions is the interim control.
• Vendor/package-name confusion if the Krilo89 namespace is a fork rather than a transfer — duplicate packages and diverging histories are a real operational trap. Resolve before writing a composer.json line.
• Client breakage from non-standard filter syntax: third-party integrators will build against filter[] per the spec and fail. Document the dialect explicitly or provide a compatibility shim.
• Transitive breakage if paknahad/jsonapi-bundle is abandoned mid-project; the fork boundary should extend to it if we go deep.

Ramp-up

• Consumers: low. RQL is learnable in an afternoon; the cost is documentation, not comprehension.
• Maintainers: low-to-moderate for a small parser, but there is no onboarding material — the initial read-through is the onboarding, and the 3.0.2 release adds no documentation to change that. Plan for a single owner with a documented handover, and avoid spreading the knowledge across a large team for a package this small.

TPM verdict: the abandonment finding is downgraded — 3.0.2 proves the project has a pulse — but the release changes nothing about the underlying decision. It ships no documented features, fixes, or compatibility claims, so it neither reduces the integration risk nor the injection-surface concerns. Adopt only if we are already on Symfony with paknahad/jsonapi-bundle; in that case it remains a cheap, contained win provided we vendor it and pin the exact release. In any Laravel context — or any context where we have not yet committed to that JSON:API bundle — the correct decision is still to port the RQL concept rather than the package, and to prefer spec-native filter[] semantics unless a specific client requires RQL. Before any spike, spend half a day resolving the Krilo89 provenance question and the 2.x→3.0 changelog gap; that is the only new work this release creates.