Weave Code
Elasticsearch Search String Parser Laravel Package
spatie/elasticsearch-search-string-parser
Parse custom search strings into Elasticsearch queries. Supports regex-based directives like status:active or @user, grouping directives, and autocomplete suggestions. Build searches via spatie/elasticsearch-query-builder and get results + directive suggestions.
Parse a search string with filters, directives and sorts to a useable Elasticsearch query
Frequently asked questions about Elasticsearch Search String Parser
- How do I install and set up this package in a Laravel project?
- Run `composer require spatie/elasticsearch-search-string-parser` and register the service provider in `config/app.php`. The package requires an Elasticsearch client (v8+) and the `spatie/elasticsearch-query-builder` for directives. Follow the README’s example to configure directives like `status:` or `@mentions` via regex patterns.
- What Laravel versions does this package support?
- The package officially supports Laravel 8+. For Laravel 7 or older, check for breaking changes in the changelog or test compatibility manually. The package leverages Laravel’s service container, so no major adjustments are needed for newer versions.
- Can I use custom search syntax like `group_by:project` or `@mentions`?
- Yes. Define custom directives using regex patterns in your `SearchQuery` configuration. For example, `group_by:project` can be parsed into a nested Elasticsearch query, while `@mentions` can map to user fields. Combine with `spatie/elasticsearch-query-builder` for complex logic.
- Does this package work with Laravel Scout for Elasticsearch?
- Yes, but it’s designed as a standalone search abstraction layer. You can use it alongside Scout or replace Scout’s search logic entirely. The package generates raw Elasticsearch queries, so you retain full control over indexing and search behavior.
- How do I handle multilingual or special characters in search strings?
- The package processes search strings as-is, so multilingual queries (e.g., `café`) or special characters (e.g., `status:high+`) are passed directly to Elasticsearch. Ensure your Elasticsearch index uses a compatible analyzer (e.g., `standard` or `icu`) for proper tokenization and matching.
- What’s the performance impact of parsing search strings at scale?
- Regex parsing adds latency, especially for high-traffic queries (>10k QPS). Mitigate this by caching parsed queries (e.g., Redis) or pre-compiling regex patterns. Benchmark with your expected query volume—complex directives may require optimization.
- How do I debug or monitor failed search queries?
- Integrate with Laravel’s monitoring tools like Sentry to log parsing errors or failed Elasticsearch requests. The package returns `SearchResults` objects, which include metadata for debugging. Log the raw search string and generated Elasticsearch query for troubleshooting.
- What if my Elasticsearch field names don’t match the search directives (e.g., `status` vs `is_active`)?
- Map directives to Elasticsearch fields in your directive classes (e.g., `status:active` → `is_active: true`). Use the `elasticsearch-query-builder` to transform directives into valid Elasticsearch DSL. Misalignment will cause runtime errors or silent failures.
- Are there alternatives for simpler search needs without custom directives?
- For basic full-text search, consider Laravel Scout’s built-in Elasticsearch support or the `elasticsearch/elasticsearch` PHP client directly. This package shines when you need custom syntax (e.g., filters, mentions) or complex query logic beyond Scout’s defaults.
- How do I add auto-completion for search directives like `status:` or `category:`?
- Use the package’s built-in suggestion feature by defining `suggest()` methods in your directive classes. For example, `status:` can return `['active', 'inactive']` as suggestions. Combine with Elasticsearch’s `completion` suggester for frontend autocomplete.
Weaver
How can I help you explore Laravel packages today?