Weave Code
Elasticsearch Query Builder Laravel Package
spatie/elasticsearch-query-builder
Lightweight fluent PHP query builder for Elasticsearch. Build searches with queries and aggregations, set index and options, then execute via the official client. Designed to pair with spatie/elasticsearch-search-string-parser; focused feature set, PRs welcome.
Build and execute an Elasticsearch search query using a fluent PHP API
Frequently asked questions about Elasticsearch Query Builder
- How do I install and set up `spatie/elasticsearch-query-builder` in a Laravel project?
- Install via Composer with `composer require spatie/elasticsearch-query-builder`. Requires the official `elastic/elasticsearch` PHP client (v8+). Initialize the `Builder` with your Elasticsearch client instance, then chain methods like `index()`, `addQuery()`, and `search()` to execute queries. Ensure your Laravel app has the Elasticsearch client configured first.
- Does this package support Laravel Scout for Elasticsearch?
- No, this package is not a direct replacement for Scout. It’s a lightweight query builder for ad-hoc searches, aggregations, or custom Elasticsearch logic. Scout’s Elasticsearch driver handles model indexing and full-text search out of the box, while this package focuses on building and executing raw queries with a fluent API.
- Can I use this with Laravel’s service container for dependency injection?
- The package itself doesn’t integrate with Laravel’s service container, but you can manually bind the `Builder` as a singleton or context-bound service. Register it in `AppServiceProvider` using `app()->singleton()` or `app()->bind()` to inject the Elasticsearch client and Builder where needed.
- What Laravel versions and PHP versions are supported?
- The package is framework-agnostic but works seamlessly with Laravel 8+. It requires PHP 8.0+. Check the [GitHub repo](https://github.com/spatie/elasticsearch-query-builder) for version-specific notes, especially if using `elasticsearch/elasticsearch` v7 (requires v1 of this package).
- How do I handle complex queries like geospatial or parent-child relationships?
- This package covers common use cases (e.g., `MatchQuery`, `RangeQuery`, aggregations) but lacks advanced features like geospatial or parent-child queries. For these, you’ll need to extend the `Builder` or use raw Elasticsearch DSL via the underlying client. Contribute a PR if you need these features!
- Can I cache query results or payloads in Laravel?
- Yes, you can manually cache query payloads or results using Laravel’s cache system. For example, cache the generated JSON payload before sending it to Elasticsearch or cache the raw results. This is useful for reducing Elasticsearch load or improving performance in read-heavy applications.
- How do I map Elasticsearch results to Laravel models or collections?
- The package returns raw Elasticsearch results (e.g., `_source` data). Manually map these to Laravel models or collections using `collect()` and hydrators. For example, use `Model::hydrate()` or a custom mapper to transform `_source` fields into Eloquent models.
- What’s the difference between this and `tntsearch/laravel-elasticsearch`?
- `tntsearch/laravel-elasticsearch` is an active-record-like ORM for Elasticsearch, tightly coupled with Laravel models. This package is a lightweight query builder for composing Elasticsearch queries manually, offering more flexibility but requiring manual mapping. Use this for custom searches or aggregations; use TntSearch for model-based indexing.
- How do I test queries built with this package?
- Test by mocking the Elasticsearch client (e.g., with `Mockery` or PHPUnit’s `createMock`) and asserting the generated query payload. Compare the output of `Builder::toArray()` to expected JSON structures. For integration tests, use a local Elasticsearch instance or a testing container.
- Does this package support multi-tenancy (e.g., index routing per tenant)?
- No, there’s no built-in multi-tenancy support. Implement this manually by dynamically setting the `index()` or using Elasticsearch’s index routing. For example, pass a tenant-specific index name or use a custom `IndexNameResolver` to route queries to the correct tenant’s index.
Weaver
How can I help you explore Laravel packages today?