Search Laravel Package

Technical Evaluation

Architecture fit

• rollerworks/search is a search-condition layer, not a search engine. You define a FieldSet (fields, comparators, value transforms), feed it raw user input or structured values, and get back a validated, serializable search-condition tree. It does not index, store, or execute anything — backend translation is explicitly someone else's job.
• That makes it a good seam between HTTP input and persistence: parse/validate once, then convert. The condition object is serializable, which is genuinely useful for saved searches, shareable filter URLs, and audit trails.
• It is a poor fit if the expectation is "a query builder." Every Eloquent-side translation is code we write and own.
• Best-fit scenario: search UIs with many filterable attributes (10+) and real comparator variety (between, gt, contains, in), or a requirement to serve the same search semantics against SQL now and a search engine later without rewriting the parser.

Integration feasibility

• There is no first-party Laravel support: no service provider, no config publish, no facade, no Eloquent bridge. The Doctrine ORM/DQL bridge is reference material, not a drop-in — Laravel's default stack gains nothing from it.
• Realistic work item is a thin internal adapter package: per-resource FieldSet definitions, a string-input processor binding, a SearchCondition → Eloquent query-builder converter, exception-to-validation-error mapping, and a field-visibility layer for authorization.
• Sizing: roughly 2–4 engineer-weeks for the first resource including a test harness; ~2–4 days per additional resource once templated.
• Composer/PSR-4 installation is trivial. Installation is not the risk; the adapter is.

Technical risk

• Adoption signal is weak (~110 stars, low opportunity score). Small user base means few published patterns, thin Stack Overflow coverage, and no ecosystem of examples to copy. Verify release metadata on Packagist directly before committing — the date in the brief warrants a second look.
• Bus factor: the Rollerworks ecosystem is small-maintainer. Assume no commercial support, no SLA, and no guaranteed PHP-version cadence.
• Surface area: the domain model is mature, but we would depend on input processors, field metadata, and caching — enough that a major bump is a real migration, not a composer update.
• Semantic mismatch with Eloquent: the comparator/type model is richer than the query builder's. Unsupported combinations must be rejected at FieldSet definition time, not discovered at query time.
• Security posture: the FieldSet is the authorization boundary. A misconfigured definition silently exposes a column to filtering. Treat definitions as access-control code.

Key questions

1. Do we need a query DSL at all, or do spatie/laravel-query-builder plus Eloquent scopes cover ~80% of the requirement at a fraction of the risk?
2. Which backends must this serve over 18 months — Eloquent only, or also a search engine / reporting store?
3. Who owns the adapter: one team's internal tool, or a shared platform component with a named maintainer?
4. What is our tolerance for a single-maintainer dependency sitting on a security-adjacent path?
5. Do we have PHP depth on-staff to fork and maintain upstream if it goes quiet?

Integration Approach

Stack fit

• Laravel 10/11/12 on PHP 8.1+; the library is framework-agnostic PSR-style PHP and slots in behind a service provider we author.
• No Octane/long-running-worker hazards beyond metadata caching — build FieldSets once and cache as singletons or config, never per request.
• Keep it at the controller/FormRequest → service boundary. Eloquent models should not know SearchCondition exists.

Migration path

• Endpoint by endpoint; do not retrofit existing endpoints wholesale.
• Phase 1: pick one filter-heavy read endpoint (ideally admin or internal). Build definition + converter + tests beside the current implementation, behind a feature flag.
• Phase 2: shadow-run — parse identical requests through both paths and assert equivalent result sets on a representative sample. This is the step that catches comparator semantics drift (case sensitivity, LIKE behaviour, null handling).
• Phase 3: cut over, keep the legacy path for one release.
• Phase 4: template the pattern and stub subsequent resources.

Compatibility

• Pin exact minor versions; patch coverage in a small ecosystem is thin and surprises are expensive.
• Validate the library's PHP constraint against our Laravel version before sizing anything.
• Cross-engine semantics: MySQL vs Postgres differ on collation and comparison. Normalize inside field transforms, not in the converter, and run the test suite against production's engine.
• If conditions are persisted (saved searches), version the serialized format now, before the first row exists.

Sequencing

1. Spike, 3–5 days: one FieldSet, one converter, one real endpoint, real data.
2. Decision gate: bake-off against spatie/laravel-query-builder on that same endpoint.
3. Build the internal adapter package plus a shared test harness.
4. Field-level authorization model with negative tests per field.
5. Per-resource rollout with observability: log rejected and normalized conditions.

Operational Impact

Maintenance

• Ongoing cost sits in our adapter, not upstream. FieldSet growth as product adds filters is cheap; library upgrades are infrequent but occasionally manual.
• Keep the adapter thin so the parser is a containable swap.
• Review upstream activity quarterly with a written tripwire: no release in 12 months, or PHP-version incompatibility, triggers a fork decision.

Support

• No vendor support, no SLA. Internal ownership is mandatory — a named maintainer with PHP depth, not a shared queue.
• Record the FieldSet/authorization convention in an ADR. Without it, each team invents its own semantics and the "one search model" benefit evaporates.

Scaling

• Runtime cost is parse + convert: CPU-cheap and request-bounded. Cache FieldSet metadata and this is a non-issue.
• The real scaling risk is query shape. Rich comparators invite unbounded OR-expansion and unindexed sorts. Add a complexity guard (max condition count, whitelisted sort fields) and require EXPLAIN review for any new comparator.
• Cap depth/count when deserializing persisted conditions.

Failure modes

• Silent over-permission — a FieldSet exposes a column the user must not filter on. Mitigate with negative tests per field; review definitions as security code.
• Environment semantic drift — collation/case differences between dev and prod. Mitigate with an engine-parity suite.
• Unhandled comparator — library exception surfaces as a 500. Map every exception to a 422 with field context.
• Unbounded query — user input produces an expensive plan. Hard caps plus statement timeouts.
• Upstream abandonment — thin adapter plus a fork contingency already scoped.

Ramp-up

• Roughly a day for an engineer to grasp FieldSet/transform/processor concepts; the domain vocabulary is the learning curve, not the code.
• Budget about a week for the first engineer including an internal written guide; later engineers onboard from the adapter's tests.
• Secondary benefit worth surfacing to product: the FieldSet doubles as a machine-readable spec of what is searchable — useful for API contracts and user-facing documentation.

Verdict: viable when we genuinely need a multi-resource search DSL with backend portability and persisted query semantics, and when we accept owning an adapter plus a fork contingency. For a handful of filters on a few endpoints, risk-adjusted cost favors spatie/laravel-query-builder or plain scopes. Low adoption and single-maintainer exposure make this "adopt deliberately, with an owner and an exit" — not a default.