Weave Code
Elasticsearch Search String Parser Laravel Package
spatie/elasticsearch-search-string-parser
Convert custom search strings like "foo bar status:active @john.doe" into ElasticSearch requests. Add directives via regex and the spatie/elasticsearch-query-builder, with grouping and autocomplete suggestions.
spatie/elasticsearch-search-string-parser converts human-friendly search strings like foo bar status:active @john.doe into executable ElasticSearch requests. Built on top of spatie/elasticsearch-query-builder, it separates free-text terms from custom directives matched via regex, then assembles the appropriate query for you.
- Define custom pattern directives (e.g.
company:aperture,@glados) with regex - Combine multiple directives plus base search terms in one call
- Basic grouping support for directives like
group_by:project - Auto-completion suggestions for supported directives
- Returns a
SearchResultsobject with results and directive suggestions
Frequently asked questions about Elasticsearch Search String Parser
- How do I install spatie/elasticsearch-search-string-parser?
- Install it with Composer by running composer require spatie/elasticsearch-search-string-parser. The package is a plain PHP library with no service provider or config file, so there is no Laravel registration step. You still need a configured Elasticsearch client and the spatie/elasticsearch-query-builder dependency available in your app.
- Does spatie/elasticsearch-search-string-parser support Laravel 11 and Laravel 12?
- The package is framework-agnostic even though its CI targets current Laravel versions such as Laravel 9, 10, 11, and 12. It has no Laravel dependency in its public API, so Laravel version support mainly means the test suite stays green. Check the Composer constraints before installing in an older Laravel app.
- How do I create a custom directive for status:active or @username?
- Create a directive class that matches the syntax you want, such as status:active or @john.doe, using a non-greedy anchored regex. The directive should emit Elasticsearch clauses through spatie/elasticsearch-query-builder, then register it with patternDirectives() when building the SearchQuery. Keep each directive small and unit-test it against realistic and adversarial strings.
- Can I use this package with Elasticsearch 8?
- The README example uses the Elastic\Elasticsearch\ClientBuilder namespace, but the package does not document explicit Elasticsearch 8 guarantees. Verify the Composer constraints because a transitive pin to elasticsearch/elasticsearch 7.x can block an ES 8 upgrade. Test against your target cluster and client version before making it load-bearing.
- How does grouping work in search strings like group_by:project?
- Grouping is basic and directive-driven: a directive can mark results for grouping, for example with group_by:project. You implement and register the directive that understands that token. The parser does not infer grouping from your index mapping automatically.
- Does spatie/elasticsearch-search-string-parser support autocomplete suggestions?
- Yes, the library supports basic autocomplete suggestions for certain directives, and directives can carry suggestion metadata. The SearchResults object can return both results and suggestions for the applied directives. You still need to implement the suggestion values inside your directive.
- Is spatie/elasticsearch-search-string-parser maintained and production ready?
- It comes from Spatie, but adoption is very low: roughly 51 GitHub stars and zero dependents in the supplied assessment. That makes it a reasonable leaf utility, not a proven critical-path search platform. Use it behind tests and a fallback if search is business-critical.
- How do I unit test custom directives and regex patterns?
- Write PHPUnit tests that instantiate each directive, parse sample search strings, and assert the generated query builder output. Include adversarial inputs such as repeated tokens, greedy matches, and malformed directives. Because the package is plain PHP, these tests do not need a Laravel bootstrapped app.
- What are alternatives to spatie/elasticsearch-search-string-parser?
- Alternatives include Elasticsearch's built-in query_string syntax, a custom parser in your app, or managed search tools like Laravel Scout with Meilisearch, Typesense, or Algolia. This package makes sense if you are already committed to Elasticsearch and want user-facing structured syntax. It does not handle indexing, mappings, analyzers, or relevance tuning.
- What are the production risks of regex-based search directives?
- Regex directives run against user input, so catastrophic backtracking can become a CPU denial-of-service risk. Use non-greedy, boundary-anchored patterns, cap input length, and test adversarial strings; the library provides no timeout or rate limit. Also watch for schema drift, because field renames can silently produce wrong or empty results.
Weaver
How can I help you explore Laravel packages today?