Laravel Cluster Laravel Package

Technical Evaluation

Architecture fit

laravel-cluster is not a thin filter helper — it is a small query language. The README describes at least seven cooperating subsystems: a parser producing an AST (ClusterQuery), a compiler that emits driver-specific SQL (MySQL/PostgreSQL/SQLite), a facade (ClusterService), a value object (ClusterVO), an Eloquent cast (ClusterCast), a collection type with in-memory filtering/aggregation (ClusterVOCollection), and Laravel macros that extend the query builder. The stated value proposition — a portable filter syntax over JSON columns, with an in-memory fallback when SQL cannot express the predicate — is a real problem for teams that ship the same product on multiple database drivers or need user-composable filters over semi-structured payloads.

Architecturally, that is the correct shape for the problem: parse once, compile per target, keep semantics in one place. The concern is scope. A DSL, a multi-dialect SQL code generator, an in-memory executor, an Eloquent cast, and query-builder macros are five separate products with five separate failure modes, and they must agree with each other semantically. For a TPM, this is the signature of a package that is powerful but expensive to own, and the adoption signals (0 stars, 0 dependents, readme/docs only) mean we would be the first real consumer — effectively adopting an unvalidated internal library.

Integration feasibility

Mechanically straightforward: Composer install, package auto-discovery, a facade and macros that hang off Laravel's existing extension points, and an Eloquent cast that attaches to a model attribute. There is no schema surgery required beyond the JSON columns we already control. That is the good news.

The real integration constraint is the driver matrix. The package's core promise — "generate SQL for different drivers" plus "custom SQLite functions" — means correctness is a function of our exact MySQL/PostgreSQL/SQLite versions, not of the package's stated feature list. Any portable-DSL package must be verified against our stack, because the fallback path (filter in PHP) can silently disagree with the compiled path (filter in SQL). If those two engines diverge, we get query results that depend on which code path executed, which is the worst class of bug to diagnose in production.

Secondary feasibility items: registering SQLite functions requires PDO-level hooks, which is not idiomatic in Laravel and interacts poorly with persistent connections (Octane/Swoole workers) if registration is not idempotent; and macros that reach into the query builder are a documented Laravel upgrade hazard across minor versions.

Technical risk

Key questions

1. What are the composer.json constraints — which Laravel and PHP versions, and is there a tagged release or only dev-main?
2. Is there a test suite, and does it include differential tests asserting SQL-path and in-memory-path return identical results?
3. How are JSON paths and operators sanitized before SQL emission, and can arbitrary raw fragments reach the compiler?
4. Which JSON operators are actually implemented per driver, and what is the documented fallback when a driver cannot express a predicate?
5. How is SQLite function registration guarded against double-registration on long-lived workers?
6. Does the in-memory path stream/chunk, or does it hydrate the full result set?
7. Is the package maintained (commit cadence, issue responsiveness), or is this a personal project published for its author's use?
8. Can we get the maintainer under a support arrangement, or is the realistic plan a maintained internal fork?

Integration Approach

Stack fit

The package sits at the query-construction layer, below our repositories and above Eloquent. That is a clean seam. The recommended fit is not "replace our filtering layer with this DSL," but "use it as an implementation detail behind an existing, team-owned filter interface." The DSL syntax must never appear in a controller, a request payload contract, or an API response schema — otherwise we couple our public contract to an unmaintained third-party grammar.

Migration path

1. Spike in a throwaway branch (1–2 days). Read composer.json; install against our current Laravel/PHP; exercise one representative query per operator class (equality, LIKE, EXISTS, nested array sub-conditions, aggregation) against each driver we run. This is a go/no-go gate, not a commitment.
2. Differential correctness harness. Before writing product code, build a fixture table and assert the SQL path and in-memory path return byte-identical results across the operator matrix. If we cannot make this pass, stop.
3. Adapter layer. Define our own ClusterFilter interface; implement it with laravel-cluster behind the facade. All product code depends on our interface only.
4. Shadow usage. Run the new path in a non-critical read surface (admin list views, internal tooling) for a release cycle and compare against existing filters.
5. Decide: adopt, fork, or discard. Given the adoption signals, plan for "fork into a vendored, internally owned package" as the default outcome.

Compatibility

Verify against our actual matrix: Laravel major/minor, PHP version, MySQL 8 JSON functions, PostgreSQL jsonb + GIN, SQLite JSON1. Treat Octane/Swoole as a separate compatibility gate because of the SQLite function registration. Also confirm behavior with read/write connection splitting and with DB::listen/query logging, since raw SQL fragments can bypass standard parameter binding visibility.

Sequencing

Parser/compiler evaluation → differential test harness → adapter + interface → shadow read path → limited production read path → full read adoption → (only then) consider write-side or aggregation usage. Do not start with aggregation operators or EXISTS/NOT_EXISTS over nested arrays; those are the highest-complexity, highest-divergence features and should be enabled last, feature-flagged.

Operational Impact

Maintenance

Assume we own it. A 0-star, 0-dependent package has no upstream incentive to fix our bugs and no community to absorb the debugging. Budget roughly 0.25–0.5 FTE for the first two quarters: writing the test suite we did not inherit, documenting the DSL internally in English, and pinning/upgrading deliberately. If the maintainer is responsive, negotiate a fork-and-upstream arrangement; otherwise vendor it and treat it as internal code with an external origin.

Support

There is no vendor, no SLA, no security disclosure process, and no version history to reason about. That is acceptable for an internal convenience library and unacceptable for anything on a revenue path. Mitigation: internal ownership named explicitly, a documented upgrade rehearsal (run the differential harness on every Laravel/PHP/driver bump), and a security review of the SQL emitter before first production use.

Scaling

Two separate scaling stories. The SQL path scales with the database, but JSON predicates are frequently non-indexable — plan on MySQL generated columns with indexes or PostgreSQL GIN indexes, and verify the generated SQL is sargable rather than wrapped in a function call. The in-memory path scales with rows scanned, not rows returned: if it hydrates a table and filters in PHP, latency and memory grow linearly and it will not survive a large table. Confirm which path any given operator takes in production code review; do not let a fallback path silently cover a hot query.

Failure modes

• Silent semantic divergence between the SQL and in-memory engines — same query, different rows depending on driver or code path. Highest-impact failure; requires the differential harness.
• Driver-specific breakage on upgrade — Laravel minor, MySQL/PG minor, or SQLite version changes alter emitted SQL or JSON operator behavior.
• Duplicate SQLite function registration on Octane workers, producing warnings, errors, or connection corruption.
• Injection through emitted SQL fragments if JSON paths or operators are attacker-influenced.
• Memory exhaustion / timeouts on the in-memory path under real data volumes.
• Incorrect aggregation semantics over nested arrays — the most intricate part of the DSL and the least likely to be covered by whatever tests exist.
• Comprehension failure — a French-only DSL with an AST most engineers have not read, debugged only by the one person who integrated it.

Ramp-up

Realistically 1–2 weeks to productive use for an engineer already fluent in Eloquent, plus 2–3 weeks to the point of being able to modify the compiler or debug a divergence. Add friction for French-only documentation. The mitigation that matters most: an internal README in English covering the ten queries we actually use, plus the differential harness as living documentation of behavior.

Recommendation

Worth a bounded spike (1–2 days) if we genuinely need a portable, user-composable JSON filter DSL — that requirement is real and the alternatives (Spatie Query Builder plus hand-written JSON predicates, or driver-specific code) are not obviously cheaper. Do not adopt on the strength of the README alone. Gate adoption on: readable version constraints, a passing differential harness on our exact driver matrix, a clean SQL-emission security review, and a named internal owner. Default expectation is a maintained internal fork, not a dependency.