Query Bundle Laravel Package

Technical Evaluation

Architecture fit. studiomado/query-bundle is a Composer-installed Laravel package that centralizes request-driven query construction against Eloquent — the filters/sorts/pagination/includes pattern that most list endpoints eventually reinvent. Architecturally that sits cleanly in the HTTP-to-query boundary: controllers stay thin, query concerns are declarative, and the package is disposable at the edges. It fits a standard Laravel monolith or modular monolith with many read/list endpoints. It does not fit non-Laravel services, GraphQL-first APIs, or teams already standardized on a query layer (e.g., spatie/laravel-query-builder, API Platform, or an in-house builder). The fit question is less "can it work" than "do we want a second convention alongside whatever we already have."

Integration feasibility. Mechanically trivial: composer require, publish config, annotate models/controllers, run a smoke test. Effort is measured in days, not sprints. The real cost is consistency — adopting it on 3 endpoints creates a convention; adopting it on 3 of 40 creates debt. With 13 stars and zero dependents, there is no public production reference to lean on, so the feasibility verdict must come from our own spike rather than from ecosystem evidence.

Technical risk. This is the dominant concern. Last release was October 2022 — pre-dating Laravel 10/11 and modern PHP 8.2/8.3 norms — so compatibility with our current framework matrix is unverified and dependency constraints may block or complicate upgrades. Bus factor is effectively one maintainer, issue traffic is presumably quiet, and there is no vendor behind it. MIT licensing means we can fork, but forking converts a dependency into owned code. Secondary risk: query-parameter surfaces are a data-exposure boundary; if filtering/sorting is permissive by default rather than allow-listed, a single endpoint can leak columns or enable expensive scans. Treat that as a design review item, not a footnote.

Key questions.

• Does it install and pass tests on our exact Laravel/PHP versions, and are transitive dependencies abandoned?
• What is the actual scope — filtering only, or sorting, pagination, relation includes, and field selection? Scope overlap with existing tooling determines whether this replaces or duplicates.
• Are filters/sorts allow-listed (safe default) or blacklist-driven?
• Is there test coverage and a security disclosure path, or is the repo effectively a code drop?
• Is there a successor package or is studiomado still actively using this internally?
• How tightly does it bind to Eloquent internals (builder macros, model traits) that major-version upgrades tend to break?

Integration Approach

Stack fit. Appropriate for a Laravel application that exposes resource-list APIs and wants a declarative query contract. Inappropriate if we are mid-migration off Laravel, or if list endpoints are few and ad hoc.

Migration path. Do not rip-and-replace. Introduce it behind a thin internal interface (QueryOptions / a base repository method) so the package is an implementation detail, not an ambient dependency. Existing endpoints keep their current code; new or actively-refactored endpoints adopt the package. That adapter is the insurance policy that makes a later swap to spatie/laravel-query-builder or a homegrown trait a contained change rather than a rewrite.

Compatibility. Pin the exact version in composer.json, run composer why-not against our framework constraint, and confirm the package's PHP and Laravel constraints match our support matrix before any code is written. Verify in CI on the same matrix we ship on, including the next framework major we plan to adopt.

Sequencing.

1. Timeboxed spike (1–2 days) on a single non-critical read endpoint, behind a feature flag.
2. Security and convention review: allow-list filters, cap page size, cap includes, forbid client-controlled sorts on unindexed columns.
3. If the spike passes, document the convention and adopt on new list endpoints first.
4. Add contract tests covering filter/sort/pagination behavior so an upgrade or swap is detectable.
5. Record an explicit fork-or-drop decision at the next Laravel major upgrade, with an owner and a date.

Operational Impact

Maintenance. We are de facto maintainers. Budget a small recurring cost — compatibility patches at each framework upgrade, dependency bumps, CVE triage — or plan to fork and vendor. The 2022 release date makes this a certainty, not a contingency.

Support. No SLA, no vendor channel, community-only. For anything on a revenue path, that means internal escalation only. The mitigation is that the code surface is small and forkable; the cost is that someone on the team must be able to read it.

Scaling. It is request-layer code, so it scales horizontally with the app. The scaling risk is query shape: unbounded includes, arbitrary sort columns, and deep pagination are the classic ways client-driven query layers turn into database incidents. Enforce server-side caps and index coverage on any sortable field.

Failure modes. (1) Framework upgrade breaks compatibility with no upstream fix — highest likelihood. (2) Permissive defaults expose fields or relations. (3) N+1 or full-table scans from client-supplied includes/sorts. (4) Silent divergence as half the codebase uses the package and half does not. (5) Abandonment with no maintainer response, leaving a fork as the only path.

Ramp-up. Low for Laravel-fluent engineers — a day to be productive. Most onboarding cost is our own convention document and the adapter, not the package API. That is also the argument for keeping the abstraction thin: it bounds both the onboarding and the exit cost.

Recommendation. Treat query-bundle as a spike candidate and reference implementation, not a critical-path dependency. Its opportunity score (3.76) is real — the problem it solves is common — but 13 stars, zero dependents, and a two-year-old release put the burden of proof on a short, contained evaluation. Proceed only if the spike shows clean compatibility with our current and next framework versions and the filtering defaults are allow-list based; otherwise adopt a maintained alternative and borrow the pattern rather than the code.