Laravel Cluster Laravel Package

Product Decisions This Supports

• Build vs. buy for advanced filtering. If your roadmap includes user-facing "saved views," faceted search, or a rules/segment builder over Eloquent models — especially models with JSON columns (settings, metadata, EAV-ish payloads) — this package is a candidate to avoid building a bespoke query parser. It provides a parser/AST, a ClusterQuery engine, Eloquent cast and collection integration, and cross-driver SQL generation (including custom SQLite functions), which is realistically weeks of work for a small team.
• Feature prioritization for filter/search capabilities. The package draws a clean line between "filter in SQL" and "filter in memory" with matching operator semantics (EXISTS/NOT_EXISTS, LIKE/NOT_LIKE, aggregation functions, sub-conditions on arrays). That makes it possible to scope a roadmap item as "parity between API filtering and client-side/export filtering" rather than two separate features.
• Segment/cohort definitions as a product artifact. Because the query format is serializable (VO/cast + collection), it supports storing user-defined filter definitions and replaying them later — the foundation for saved audiences, alerting rules, or admin-configurable dashboards.
• API surface design. A single, validated query-grammar for ?filter= style endpoints reduces the number of bespoke query params per resource and gives you one place to enforce allowed fields/operators — a governance decision, not just a technical one.
• Use cases where it fits naturally: internal admin/back-office filtering, reporting exports where filters must be reproducible, multi-tenant config/metadata lookups, and products where end users compose their own conditions.
• Risk-adjusted decision: with 0 stars, 0 dependents, a single-author namespace, and documentation written in French, treat this as source to vendor or fork, not as an ecosystem-standard dependency. The decision to adopt is really a decision to own a fork.

When to Consider This Package

Consider it when:

• You have a concrete, near-term requirement to filter on JSON columns with a composable grammar, and existing Eloquent scopes are already becoming unmaintainable.
• You need behavioral parity between database filtering and in-memory collection filtering (e.g., server-side pagination plus client-side/CSV-export filtering) — the package's dual engine is its most distinctive capability.
• You run multiple database drivers (MySQL/PostgreSQL/SQLite) in dev/prod/test and need filter SQL to behave consistently, including SQLite custom functions for tests.
• Your team can read and own PHP internals: you are prepared to pin a commit, vendor the code, add your own test suite, and accept maintenance.
• You can constrain the blast radius: filters are validated against an allowlist, and the package is used behind your own service layer rather than called ad hoc from controllers.

Look elsewhere when:

• You need production-grade support signals — a maintainer SLA, security advisories, semver releases, or a contributor community. Zero stars and zero dependents means zero external validation; assume no one else has run this in production.
• Documentation language or onboarding matters for team velocity — the README is a comprehensive French manual; that is a real cost for non-Francophone teams and for future hires.
• You only need simple filters (where, whereIn, date ranges). Laravel's query builder, local scopes, or a lightweight query-builder package get you there with far less surface area.
• You need search relevance, typo tolerance, or faceting at scale — that is a search-engine problem (Scout/Meilisearch/OpenSearch), not a query-parser problem.
• Your JSON filtering needs are shallow and stable — Postgres ->> / MySQL JSON_EXTRACT wrapped in a handful of scopes is cheaper to own than a full grammar.
• You are in a regulated or security-sensitive context where unaudited query-string-to-SQL translation is a hard no without a full internal review.

How to Pitch It (Stakeholders)

For executives (one paragraph): We have a recurring class of feature requests — saved filters, admin segments, filterable exports — that we currently rebuild one-off each time, and each rebuild carries subtle inconsistency between what the API filters and what the UI/export filters. This package is an existing implementation of that capability, including the hard part (JSON columns across database engines). The catch is maturity: it has no community traction and a single maintainer, so the proposal is not "adopt a dependency" but "acquire ~N weeks of engineering and own it." I recommend a time-boxed spike with a written go/no-go, not a roadmap commitment.

For engineering:

• What it is: a cluster/filter query parser with an AST, a central ClusterQuery engine, an Eloquent cast, an intelligent VO collection, and SQL generation for multiple drivers with SQLite custom functions for tests.
• Why it's interesting: parity between SQL-side and in-memory filtering with the same operator set, plus array sub-conditions and EXISTS/NOT_EXISTS. That is genuinely hard to get right twice.
• What we'd have to do: vendor the source, pin it, add tests and fixtures (none are evident from the docs), audit the parser for injection and unbounded-cost queries (deeply nested conditions, expensive JSON paths), enforce a field/operator allowlist at the boundary, and document the grammar internally in English.
• What we'd learn fast: a two-week spike wiring the parser to one real resource with JSON columns, measuring query plans on our actual data volume, and confirming the in-memory engine matches SQL results on a randomized corpus.
• Recommendation: approve the spike; defer the roadmap line until we have the spike write-up, an ownership owner, and a fallback plan (scopes + database-native JSON operators) documented.