Pipeline Query Collection Laravel Package

Technical Evaluation

Architecture fit l3aro/pipeline-query-collection is a lightweight, single-purpose Laravel package that lets query constraints be expressed as composable pipeline stages applied to an Eloquent query/collection. Architecturally it sits in the read path between controllers/form requests and the persistence layer — the same niche as spatie/laravel-query-builder or hand-rolled filter classes. It has no infrastructure footprint (no migrations, no service providers that touch the container beyond binding, no queue workers, no external services), so it does not alter our deployment topology or data model. Fit is good where we have repeated, user-driven filtering/sorting surfaces (admin tables, reporting screens, API index endpoints) and poor where we have fewer than ~3 such surfaces, since the abstraction cost won't amortise.

Integration feasibility High. Adoption is a Composer require plus per-resource pipeline definitions; there is no schema change and no data backfill, so it can be trialled on a single endpoint behind a feature flag and reverted by reverting one dependency. The v1.6.0 release adds Laravel 13.x compatibility, which signals the maintainer intends to track framework majors — a positive leading indicator for a package we would be pinning in composer.json for multiple years. Note that the Laravel 13 support arrived via an automated laravel-shift PR, which tells us the repo has a CI matrix that the bot could target, but does not by itself prove behavioural coverage on 13.x.

Technical risk

• Bus factor (high): single-maintainer community package. Any abandonment leaves us owning a fork. This is the dominant risk and is not mitigated by this release.
• Adoption/ecosystem risk (medium): niche package; fewer public production references and Stack Overflow answers than spatie/laravel-query-builder, meaning our engineers debug from source rather than from documentation.
• Semantic drift risk (medium): pipeline packages define their own ordering/composition semantics. If those diverge from what our team expects of the query builder, subtle filter-combination bugs appear in production rather than in tests.
• Version risk (low, reduced by this release): prior to v1.6.0 we would have been capped at Laravel 12.x. That constraint is now lifted, so the package no longer blocks a framework upgrade — this is the single most material change in the release.
• Upgrade risk (low): a 1.5.0 → 1.6.0 minor bump with a compat-only changelog implies no breaking API change.

Key questions

1. What is the package's test matrix and coverage on Laravel 13.x, and does CI run against the lowest supported PHP?
2. Are there any transitive dependencies, and do any of them have their own Laravel major constraints that could re-block us?
3. Who is the maintainer, what is their release cadence over the last 12 months, and is there a stated support/EOL policy?
4. Do the pipeline ordering and short-circuit semantics match our existing filter conventions, or will engineers need a mental model translation?
5. Can we express our current filters 1:1, or does the package's abstraction force query rewrites that change generated SQL?

Integration Approach

Stack fit Fits a conventional Laravel monolith or modular monolith on Eloquent. It is a read-side convenience layer only — it does not help with writes, transactions, or cross-service queries. If our services are API-first with thin controllers, the package composes cleanly with FormRequests (validation) and API Resources (serialisation), occupying the same seam our controllers currently fill with inline ->when() chains.

Migration path Incremental and reversible, in this order:

1. Spike: implement one existing index endpoint's filters through the package in a branch; diff the generated SQL against the current implementation for a representative set of query strings.
2. Wrap: expose the package behind a thin internal interface (e.g. App\Support\Query\FilterPipeline) so application code depends on our contract, not the vendor namespace. This is the key de-risking step and makes a future swap to native Eloquent or an alternative package a contained change.
3. Adopt: migrate remaining endpoints one per PR, each with characterisation tests asserting response parity.
4. Constrain: pin to ^1.6 and add a Composer audit/lock-review step so a future major requires deliberate review.

Compatibility v1.6.0 supports Laravel 13.x and, by implication, the majors the maintainer still tests. Before adopting, confirm our current Laravel/PHP pair is inside the tested matrix rather than merely inside the composer.json constraint — the two are not the same guarantee. No known conflicts with common companion packages, but verify against our actual dependency graph in CI, not on paper.

Sequencing Adopt only after (a) PHP/Laravel upgrade work for the current cycle is closed, so a package upgrade and a framework upgrade don't land in the same release, and (b) the internal abstraction wrapper exists. Treat the framework-major-compatibility property as a standing gate: on each Laravel major, confirm a compatible package release exists before scheduling our own upgrade, and record this package in the upgrade runbook as a dependency that has historically lagged.

Operational Impact

Maintenance Near-zero steady-state: no runtime services, no scheduled jobs, no config to drift. The real maintenance cost is dependency stewardship — tracking releases, validating each Laravel major, and being prepared to fork. Budget a nominal recurring review rather than a project.

Support Community-only. No vendor SLA, no paid support tier. Internal ownership must be assigned explicitly — name a code owner for the wrapper layer so the package never becomes orphaned code that nobody feels responsible for. Documentation for onboarding should be written by us against our wrapper, not delegated to the upstream README.

Scaling Effectively neutral. The package shapes queries; it does not execute them differently. Scaling behaviour is therefore governed by the indexes and query plans our pipelines generate, not by the package. The one caveat: if pipeline stages are materialised as in-memory collection operations rather than SQL, large result sets will move work from the database to PHP — validate that filters compile to SQL for any endpoint expected to exceed a few thousand rows.

Failure modes

• Silent semantic change: a minor upgrade alters how stages compose, producing wrong-but-plausible result sets. Mitigation: characterisation tests asserting exact result sets, not just HTTP 200.
• Upgrade blockage: a future Laravel major ships before a compatible package release, holding our platform back. Mitigation: wrapper layer plus a pre-agreed fork-and-patch playbook.
• Abandonment: maintainer stops publishing. Mitigation: fork rights confirmed, wrapper keeps blast radius to one directory.
• Filter injection / unbounded queries: user-supplied filter keys reaching pipeline definitions without allow-listing. Mitigation: explicit allow-list per endpoint, plus mandatory pagination caps.
• N+1 regressions: filters that trigger lazy-loaded relations. Mitigation: query-count assertions in tests for adopting endpoints.

Ramp-up Low for engineers already fluent in Eloquent — roughly half a day to a day to internalise pipeline semantics, provided we publish one reference implementation and the wrapper's contract. The cost is concentrated in review discipline (SQL diffs, result-set parity) rather than in learning the API. If the team is unfamiliar with pipeline/composable-filter patterns generally, add a short internal walkthrough; that's the only place this package introduces a new idea rather than a new tool.