Product Decisions This Supports
- Feature scoping for queryable APIs — still Symfony-only. If we expose list endpoints that need
filter, sort, and range-style querying, this package is a thin adapter between an RQL query string and a Doctrine finder, layered on top of paknahad/jsonapi-bundle. It shortens the path from “we need flexible filtering” to a working endpoint, but only for teams already on that bundle.
- Framework fit check — flag before anything else. Despite being filed under “Laravel/PHP,” this is a Symfony bundle for a Symfony JSON:API implementation. It is not usable in a Laravel application without substantial rework. If our stack is Laravel-first, this is out of scope and the decision is effectively closed.
- Build vs. buy — maintenance signal has changed, but not the conclusion. The new 3.0.2 release invalidates the prior “no release since 2022-05-09” statement. However, the release notes are a develop → master merge with no described features, fixes, deprecations, or compatibility work. That is better than no release, but it is not evidence of an active maintenance program. The surface area remains small (RQL parsing + Doctrine finder glue), so “buy” saves days, not months. The real cost remains maintenance ownership: the prior public signals were very thin, and a merge-only patch release does not establish a security response path or version-support guarantee.
- Roadmap signal, not a roadmap driver. This should never be the reason we adopt
paknahad/jsonapi-bundle; it is only a convenience if that dependency already exists. Treat it as an accelerant for a spike or an internal/admin API, not as a platform commitment.
- Use cases where it earns its keep. Internal admin tooling, partner read-only APIs with ad-hoc filtering, and prototypes where we want RQL-style query strings without writing a parser. In these contexts a small, forkable MIT package is an acceptable trade — provided we verify the new 3.0.2 release installs cleanly on our PHP/Symfony versions.
- Use cases where it does not. Public, long-lived, SLA-backed APIs; anything requiring a security response path; anything needing current PHP/Symfony version support guarantees; and any Laravel application.
When to Consider This Package
Adopt (or, more accurately, trial) it only when all of the following hold:
- We are already running
paknahad/jsonapi-bundle on Symfony and want RQL-style filtering without building it ourselves.
- The workload is internal, prototype, or short-lived, so an unmaintained dependency is tolerable.
- Engineering is willing to vendor or fork the package and own it. The 3.0.2 release is a develop→master merge, so it does not reduce the need to assume we own the code.
- We have verified it installs and runs against our current PHP/Symfony versions — and specifically that the new 3.0.2 release works in our environment. A patch release with no compatibility notes is not a compatibility guarantee.
Look elsewhere when:
- The stack is Laravel. Use
spatie/laravel-query-builder, native Eloquent scopes, or Laravel’s query builder. This package does not apply.
- We need maintained dependencies. The 3.0.2 release is a positive maintenance signal versus the prior assessment, but it is a merge-only patch release and does not by itself provide CVE response, version bumps, or upstream fixes. Treat maintenance risk as reduced only slightly.
- We need JSON:API compliance or broad filter semantics. API Platform’s filter system (Symfony) or the upstream bundle’s own query support is the safer, better-supported route.
- We need support, SLAs, or a vendor relationship. None of that exists here.
- We just need simple filtering. A small in-house parser is likely cheaper over a 12-month horizon than owning a fork.
How to Pitch It (Stakeholders)
For executives: This is a small, MIT-licensed convenience library that lets Symfony-based JSON:API endpoints accept flexible query strings (filter/sort) with minimal custom code. A new 3.0.2 patch release exists, but its changelog is a develop→master merge with no described features or fixes. It remains non-strategic, has no vendor behind it, and should not become a platform dependency. Recommendation: do not make it a platform dependency. At most, approve a short engineering spike (a few days) if we already run paknahad/jsonapi-bundle; the fallback — building the equivalent in-house — is on the order of one to two weeks and gives us full ownership.
For engineering: Single-purpose Symfony bundle: translates RQL into a Doctrine finder for paknahad/jsonapi-bundle. Tiny, forkable, MIT. The new 3.0.2 release is a develop→master merge from 3.0.1, with no feature, fix, deprecation, or compatibility detail in the notes. That replaces “no release since 2022” with “a patch release exists, but active maintenance is still unproven.” If we trial it, plan to vendor it and assume we own the code, and verify 3.0.2 against our PHP/Symfony versions. If the team is on Laravel, stop here — it’s a Symfony bundle and does not apply; use spatie/laravel-query-builder instead.