Qarray Laravel Package

Technical Evaluation

Architecture fit. qarray is a standalone, framework-agnostic PHP library that layers SQL-like query semantics over native PHP arrays. In a Laravel codebase its overlap with Illuminate\Support\Collection (where, filter, pluck, groupBy, sortBy) and with Eloquent is substantial — the majority of routine use cases are already served by first-party, well-maintained primitives. The genuinely differentiated slice is narrow but real: string-driven, dynamically composed predicates, where a query is stored or transmitted as data rather than code (saved user filters, admin-configurable report criteria, rule definitions in config/DB). That is a legitimate need; it just isn't the common need.

Integration feasibility. Mechanically high. Composer install, PSR-4 autoload, no service provider required for core use; any Laravel binding is a thin wrapper at most. Time to a working call is hours. The real cost is not integration effort — it's the dependency decision itself.

Technical risk. A single-maintainer package with ~106 stars and a low opportunity score, no vendor backing. CC0-1.0 is a public-domain dedication rather than an OSI software license: it carries no explicit patent grant, and legal/procurement will likely flag it. The offsetting benefit is significant — CC0 lets us vendor, modify, and relicense internally with zero friction, which materially defuses the lock-in and abandonment risk. Runtime risk concentrates in the parser: if query strings ever originate from users, it needs review for complexity limits, error semantics, and any dynamic evaluation.

Key questions.

• Which PHP versions and which illuminate/support (if any) constraints? Laravel 11/12 supported?
• Any transitive dependencies that conflict with the app's existing composer constraints?
• How are nested arrays, dot notation, and mixed types handled under PHP 8 strict comparison?
• Is there a guard on query complexity, and does malformed input throw or silently return empty?
• Does the parser rely on eval() or an expression-language dependency? (drives the security review)
• Test coverage, CI matrix, issue response time, and history of breaking changes on minor releases?
• Are inputs mutated, or are results immutable?

Integration Approach

Stack fit. Pure PHP and framework-agnostic, so it fits any Laravel version at the language level. Its value is lowest wherever Eloquent already applies and highest as a "query as data" layer: report builders, saved filters, config-driven eligibility rules, and cached third-party payloads.

Migration path. Do not replace Collection usage. Introduce qarray behind a small internal interface (e.g., an ArrayQueryEngine contract) with two implementations — qarray and a native Collection fallback. That makes any pilot reversible in an afternoon and gives a permanent exit hatch if the package is abandoned.

Compatibility. Pin the exact version, run a lockfile-diff check in CI, and confirm PHP + Laravel support in the matrix before piloting. Because CC0 permits it, take a vendor/fork snapshot if the pilot succeeds — this converts an external dependency into an internal, patchable one.

Sequencing.

1. Half-day spike: reproduce two or three real filter requirements from the backlog in qarray vs. Collection; compare LOC and readability.
2. Adapter plus contract tests asserting identical output to the Collection implementation across representative fixtures.
3. Pilot on one non-critical surface (internal admin report or config-driven rule set) behind a feature flag.
4. Benchmark at realistic volumes (1k / 10k / 100k rows) before any wider rollout.
5. Go/no-go: adopt-wrapped, fork, or discard — with discard cost kept near zero.

Operational Impact

Maintenance. Single maintainer, small user base, unclear cadence beyond the 2024-12-18 release. Plan to own patches. The adapter boundary plus CC0 fork rights bounds ongoing cost to the wrapper we control.

Support. Community-only, GitHub issues, no SLA, no commercial backing. The escalation path is "read the source" — tolerable for a self-contained parser, not tolerable on a critical path without the fork in place.

Scaling. Strictly in-memory, O(n) per predicate, no indexes; the ceiling is memory_limit and every query materializes a result set. Comfortable at thousands of rows per request; at tens of thousands, expect latency and memory to surface in profiling. It is not a substitute for SQL — anything that grows unboundedly belongs in the database.

Failure modes. Malformed query strings (throw vs. silent empty result — both painful without explicit handling); type-coercion surprises under PHP 8; unbounded complexity from user-supplied predicates (a DoS surface); memory exhaustion on large arrays; dependency abandonment. Each maps to a concrete guard: validation on stored queries, try/catch at the adapter, a row-count ceiling before dispatch, and the fork option.

Ramp-up. Low for anyone fluent in Eloquent or SQL — the fluent API feels familiar within an hour. The hidden onboarding cost is semantic: developers will assume Eloquent behavior (null handling, type juggling, operator support) and be wrong at the edges. Document actual semantics in the adapter, not by pointing at the vendor README.

Verdict. Narrow scope, cheap to trial, moderate risk to depend on. Worth a bounded pilot only if the "query as data" requirement is real and recurring; otherwise native Collection covers the need at zero dependency cost.