Weave Code
Elasticsearch Query Builder Laravel Package
spatie/elasticsearch-query-builder
Lightweight fluent PHP query builder for Elasticsearch. Build and execute searches with an ergonomic Builder API: set index, add queries, aggregations, sorting, and filters, then run search() against the official Elasticsearch PHP client.
Build and execute an Elasticsearch search query using a fluent PHP API
Frequently asked questions about Elasticsearch Query Builder
- Can I use this package to replace Laravel Scout’s Elasticsearch queries entirely?
- This package is designed to supplement or replace Scout’s default queries for advanced use cases. While Scout handles basic full-text search, this builder lets you craft complex queries (e.g., aggregations, nested filters) without manual JSON. For full replacement, ensure your app’s search logic aligns with the builder’s supported features.
- What Laravel and Elasticsearch versions does this package support?
- The package requires PHP 8.1+, Laravel 9+, and Elasticsearch PHP client v8+. It’s optimized for Elasticsearch 8.x but may lag behind minor updates. Check the [README](https://github.com/spatie/elasticsearch-query-builder) for version-specific notes if using older setups.
- How do I install and configure this in a Laravel project?
- Install via Composer: `composer require spatie/elasticsearch-query-builder`. No additional configuration is needed beyond setting up the Elasticsearch PHP client (e.g., `elasticsearch/elasticsearch`). Inject the client into the `Builder` class, then chain queries like `Builder::index('posts')->addQuery(MatchQuery::create('title', 'laravel'))`.
- Does this builder support nested or geospatial queries?
- The package is lightweight and explicitly lacks support for advanced features like nested queries or geospatial searches. For these, you’d need to extend the builder manually or use raw Elasticsearch queries. Check the [GitHub issues](https://github.com/spatie/elasticsearch-query-builder/issues) for community workarounds.
- How can I test queries built with this package?
- Use Laravel’s testing tools to mock the Elasticsearch client (e.g., with Mockery) and verify query generation. For integration tests, compare results against Elasticsearch’s actual responses. The package includes unit tests but lacks Laravel-specific test examples—you may need to adapt existing Elasticsearch test suites.
- Will this package work with Laravel Scout’s Elasticsearch driver?
- Yes, this builder can complement Scout by handling custom search logic beyond Scout’s default capabilities. For example, use it to add aggregations or complex filters to Scout-indexed models. However, Scout’s default queries won’t automatically use the builder—you’ll need to integrate them manually.
- Are there performance concerns with fluent query building?
- Fluent builders generate verbose JSON payloads, which may impact query construction time for highly complex searches. Mitigate this by caching query strings (e.g., via Laravel’s cache) or pre-building queries in services. Benchmark against raw DSL for your specific use case.
- How do I handle errors like invalid queries or connection issues?
- The package doesn’t include built-in error handling for Elasticsearch issues. Wrap queries in try-catch blocks or use Laravel middleware to log errors or retry failed requests. The Elasticsearch PHP client throws exceptions for connection/query errors, which you can catch and handle as needed.
- What alternatives exist for building Elasticsearch queries in Laravel?
- Alternatives include raw Elasticsearch PHP client usage, packages like `ruflin/elastica` (for lower-level control), or Scout’s built-in query methods. This builder stands out for its Laravel-fluent syntax and integration with Spatie’s ecosystem (e.g., `elasticsearch-search-string-parser`). Choose based on your need for simplicity vs. flexibility.
- How can I contribute or request missing features?
- The package is open-source and accepts pull requests. For missing features (e.g., nested queries), check the [GitHub issues](https://github.com/spatie/elasticsearch-query-builder/issues) or submit a new one. The maintainers are responsive and encourage community contributions, especially for niche use cases.
Weaver
How can I help you explore Laravel packages today?