Weave Code
Elasticsearch Query Builder Laravel Package
spatie/elasticsearch-query-builder
Lightweight fluent PHP query builder for Elasticsearch. Build searches, filters, and aggregations with a clean API, then execute via the official client. Designed to pair with Spatie’s search-string parser; covers common use cases and is easy to extend.
Build and execute an Elasticsearch search query using a fluent PHP API
Frequently asked questions about Elasticsearch Query Builder
- How do I install this package in a Laravel project?
- Run `composer require spatie/elasticsearch-query-builder` in your project directory. Ensure you also have the official Elasticsearch PHP client (`elasticsearch/elasticsearch`) installed, which is a dependency. For Laravel, you can configure the Elasticsearch client in a service provider or use Laravel’s config files for centralized management.
- Does this package support Laravel’s Eloquent ORM for hybrid search?
- Yes, the package is designed to work alongside Eloquent. You can use it to build Elasticsearch queries for full-text search while keeping your database queries in Eloquent. The fluent API mirrors Laravel’s query builder style, making it intuitive for developers familiar with Eloquent’s syntax.
- What Laravel versions does this package support?
- The package is framework-agnostic but works seamlessly with Laravel 8.x, 9.x, and 10.x. It leverages PHP 8.1+ features and the official Elasticsearch client, which is compatible with modern Laravel applications. Always check the package’s `composer.json` for the latest PHP/Laravel requirements.
- Can I use this for aggregations like faceted search in Laravel?
- Absolutely. The package includes built-in support for aggregations like `MaxAggregation`, `AvgAggregation`, and `TermsAggregation`. You can chain aggregations to your queries using methods like `addAggregation()`, making it easy to implement faceted search, analytics, or metrics in Laravel applications.
- How do I handle Elasticsearch errors in Laravel’s exception handling?
- Elasticsearch errors are propagated directly from the official client. To integrate with Laravel’s exception handling, wrap the `search()` call in a `try-catch` block and throw a custom `ElasticsearchException` or use Laravel’s `throw_if` helper. Alternatively, create a decorator around the Builder to standardize error responses.
- Is there a way to cache Elasticsearch query results in Laravel?
- Yes, you can cache query results using Laravel’s cache layer (e.g., Redis or file cache). Store the results of `Builder::search()` in cache with a unique key, such as a hash of the query parameters. Invalidate the cache when data in Elasticsearch changes, like after bulk updates or index refreshes.
- What if my use case requires Elasticsearch features not covered by this package?
- For unsupported features (e.g., script queries, runtime fields, or ML features), you can extend the Builder using traits or decorators. Alternatively, fall back to raw JSON payloads by accessing the underlying Elasticsearch client via `$builder->getClient()->search()`. The package is designed to be extensible via PRs if you need broader support.
- How do I test queries built with this package in Laravel?
- The Builder class is mockable, allowing you to test search logic in isolation. Use PHPUnit or Mockery to mock the Elasticsearch client and verify query construction. For integration tests, use Laravel’s `RefreshDatabase` or `RefreshElasticsearch` traits (if available) to reset your Elasticsearch index before each test.
- Does this package work with Elasticsearch clusters or only single nodes?
- The package works with both single-node and clustered Elasticsearch deployments. Configure the official Elasticsearch client (e.g., connection pooling, retry logic, or circuit breakers) in your Laravel service provider or config files. The Builder will use these settings to interact with your cluster.
- What are the alternatives to this package for Laravel Elasticsearch queries?
- Alternatives include raw Elasticsearch client usage, `elasticsearch/elasticsearch-laravel` (a Laravel-specific wrapper), or `scout-elasticsearch` (if using Laravel Scout). This package stands out for its fluent API, which reduces boilerplate and aligns with Laravel’s conventions. Choose based on your need for simplicity (this package) or advanced Scout integration.
Weaver
How can I help you explore Laravel packages today?