Elasticsearch Search String Parser Laravel Package

Product Decisions This Supports

• Build vs. buy on "power-user search." The recurring internal debate is whether to ship key:value operator syntax (the Slack/GitHub/Jira pattern users already know) or keep a single text box. This package prices that decision at roughly a sprint of directive authoring instead of a quarter of parser engineering — which changes the calculus from "not now" to "ship one directive and measure."
• Roadmap sequencing for search as a feature area. Each user-facing operator maps to one directive class (filter, sort, mention, group_by). That gives you a natural, per-ticket roadmap: "status filters" → "assignee mentions" → "saved sort" → "facets/aggregations," each independently shippable and reversible.
• Search UX investment order: expressiveness vs. relevance. This package solves query expressiveness (letting users say exactly what they mean) and discoverability (it returns suggestions alongside results). It does not solve relevance ranking, typo tolerance, or synonyms — those remain Elasticsearch index/tuning work. Use it to decide whether your search complaints are "I can't filter" or "results are bad," because only the former is addressed here.
• Scope control on internal tooling. The strongest near-term use case is admin/support/CRM/order-list search, where users already think in status:active. That's a contained bet with no public-facing syntax contract to support or deprecate.
• Differentiation bets for search-heavy products. If a search bar is core to your value prop, operator syntax is a defensible wedge against lighter competitors. The price of admission is a real UX plan for autocomplete, error states, and a "help" surface (see risks below).
• Vendor strategy. MIT, small, self-hosted, and only a thin string→query layer over spatie/elasticsearch-query-builder. Adopting it does not create meaningful lock-in — the directives you write are your own domain logic and survive a swap.
• Not a decision it supports: replacing a managed search product (Algolia/Typesense/Meilisearch) on the public storefront. It assumes you're already committed to Elasticsearch and its operational cost.

Known costs to budget for, not just the code:

• Thin documentation. The README's ## Usage block is an unedited Spatie skeleton stub with an echoPhrase('Hello, Spatie!') example that has nothing to do with the package. Real learning requires reading the abstract directive classes in src/. Onboarding cost lands on your team, not the vendor.
• Two packages, not one. You are also adopting spatie/elasticsearch-query-builder and its clause semantics.
• Regex-based parsing, not a grammar. Directive matching is pattern-and-strip, run in registration order. That means no free quoting, no boolean precedence, and greedy patterns can silently cannibalize later ones. Users will type status:"active, pending" and get surprising results. Plan for an error/empty-result experience.
• Version pinning is a support ticket. ^2.0 = Elasticsearch 8 + the 8.x PHP client. ES7 clusters must stay on 1.x, and mismatches fail at the client layer with errors that look like parser bugs.
• Maturity signal. 51 stars and zero known dependents: the package is Spatie-maintained and framework-current, but the community surface is essentially nil. Changelog activity is largely Laravel-version and ES8 compatibility bumps — healthy maintenance, not heavy feature velocity.

When to Consider This Package

Adopt when most of these are true:

• You are on Elasticsearch 8 with the matching elasticsearch/elasticsearch 8.x PHP client, on Laravel/PHP. (On ES7, the 1.x line exists but you're on a legacy branch — treat as a maintenance-only position.)
• The audience is internal or expert users — support console, admin order list, CRM, log/ops tooling — where key:value is a help, not a hurdle.
• You can name one to three concrete directives today (status:, @assignee, company:) rather than a speculative syntax.
• You already have (or are willing to build) the hydration layer: get ES hit IDs, then load models from the database and preserve ES ordering.
• You want suggestions/autocomplete for operators and are willing to own the UX around them.
• You have PHP engineering capacity to read source rather than docs, and to own directive design long-term.

Look elsewhere when any of these hold:

• You need a real query grammar — quoted phrases, AND/OR/NOT, parenthetical grouping, wildcards, range operators. Regex-per-directive will fight you. Build or adopt an actual parser (or lean on Elasticsearch's own query_string/simple_query_string with carefully controlled inputs) instead.
• The interface is public-facing and consumer-grade. Typo tolerance, relevance tuning, synonyms, and zero-training discovery are the product requirements; a managed search service or ES relevance work should consume that budget first. Operator syntax on a public homepage is a power-user feature with a small audience.
• You aren't on Elasticsearch already. Adopting ES plus this package to get a search bar inverts the cost/benefit.
• You need vendor SLA, security review, or LTS guarantees. MIT + Spatie + 51 stars is fine for an internal tool; it is not a procurement-approved dependency.
• Elasticsearch 7 is a hard constraint and staying there — pinning 1.x for new work means starting on a branch that receives compatibility attention, not features.
• Non-PHP stack for the search layer, or you need parsing shared across services (a Node/Python/Go front door). The parser lives where the query executes.
• You need the search to be multi-tenant/permission-aware at the query level and aren't prepared to enforce that inside your base directive — the package does not provide it, and getting it wrong is a data-leak bug, not a search-quality bug.

Recommended first commitment if you proceed: one internal screen, one base directive plus one pattern directive, shipping within a sprint. That surfaces the real questions — greedy regex interaction, empty-remainder behavior, hit hydration — at a fraction of the cost of discovering them behind a public feature.

How to Pitch It (Stakeholders)

To executives (30 seconds): Users of modern tools expect to type status:active @sarah and get exactly what they asked for. Today we can't offer that without building and maintaining a query parser, which is a quarter of engineering plus permanent upkeep. This package — MIT-licensed, from Spatie, a well-known PHP vendor — turns that into a per-sprint line item: one operator, one small class, one release. It's cheap to try, cheap to abandon, and the operator logic we write stays ours either way.

To engineering: It's a thin dispatcher, not a search engine. You declare regex-based directives; each match is applied through spatie/elasticsearch-query-builder and stripped from the string; the remainder goes to a single base directive. You get grouping and directive suggestions for free in a SearchResults object. Zero lock-in — our directives are plain PHP.

The three things to be honest about up front:

1. This is a small, lightly adopted package (51 stars, no known dependents). Spatie maintains it and keeps it framework-current, but we're early adopters, not riding a crowd. It's a dependency we can afford to fork or replace — the directives are ours.
2. Docs are thin and the README's usage example is a placeholder. Budget a day of source-reading for the first directive; assume the team owns the real documentation.
3. Parsing is regex-and-strip in registration order, not a grammar. No boolean operators or quoting out of the box, and greedy patterns can misfire. That means we must design the failure experience and a short help/legend — and it means we should scope this to internal, expert users first, not the public site.

What it is not: it does not improve relevance. If the complaint driving this initiative is "the results are wrong," this is the wrong investment — that's index design and ranking tuning. If the complaint is "I can't narrow it down," this is the fastest path we have.

Ask: approve a one-sprint spike on an internal screen — one base directive, one pattern directive, measured against whether users actually type the operator. Success criteria: operator usage rate and a reduction in filter-clicks per search. If it doesn't earn the second directive, we stop with almost nothing sunk.