Weave Code
Elasticsearch Dsl Laravel Package
handcraftedinthealps/elasticsearch-dsl
A fork of ongr/elasticsearch-dsl for building Elasticsearch queries in PHP with a fluent DSL. It extends support to a wider range of Symfony (3.4 through 7.x) and Elasticsearch versions, and powers the handcraftedinthealps Elasticsearch bundle.
Fork of ongr-io/ElasticsearchDSL providing Symfony 5 support for different elasticsearch versions.
Frequently asked questions about Elasticsearch Dsl
- How do I install handcraftedinthealps/elasticsearch-dsl in a Laravel application?
- Run composer require handcraftedinthealps/elasticsearch-dsl. There is no service provider, facade, or config file to publish, because it is a plain library rather than a Laravel package. You instantiate query objects directly inside your own search services or wrapper classes. You will also need a transport client such as elasticsearch/elasticsearch to actually execute the requests.
- Do I need Symfony to use this package in Laravel?
- No. The Symfony version matrix in the README describes the companion handcraftedinthealps/elasticsearch-bundle and its service wiring, not the DSL library itself. The DSL is framework-agnostic and lives in the ONGR\ElasticsearchDSL namespace, so Composer autoloading is all Laravel needs. Ignore the bundle entirely and treat it as a standalone query builder.
- Which Elasticsearch versions are supported, and does it work with Elasticsearch 8?
- The README compatibility table caps at Elasticsearch ^7.0, but the release history includes 8.x branches from 8.0.0 through 8.3.0 with ES 8 support, runtime fields, kNN search, and parent aggregations. The documentation is inconsistent with the release history, which is itself a risk signal. Verify branch-to-cluster compatibility empirically by running real queries rather than trusting the table.
- Is this a drop-in replacement for ongr/elasticsearch-dsl?
- Yes. It is a maintained fork that keeps the same namespace and API surface while extending support to a wider range of Symfony and Elasticsearch versions. You can swap the Composer requirement and keep your existing query-building code. Just pin the branch that matches your production Elasticsearch version.
- How do I build a bool query with filters and aggregations using this DSL?
- Create a Search object, attach a BoolQuery with must, should, and filter clauses, add your aggregations, then call toArray() to get the request body. That array is passed straight to your client's search call. Sorting, nested fields, and mappings are also modeled as typed objects, so the whole request can be composed fluently.
- How do I test queries built with the DSL?
- Because every query object serializes to a deterministic array, you can assert on the array or JSON output in unit tests without an Elasticsearch cluster. Build the query in a service method and assert that toArray() matches the expected structure. Integration tests against a live cluster are only needed for cluster-level behavior.
- Can I use this package with elasticsearch/elasticsearch or Laravel Scout?
- Yes. The DSL only produces request arrays and owns no connections, pooling, retries, or cluster state. Pass the serialized query to the official elasticsearch-php client, a Scout custom driver, or any other transport you already use. Hosts, credentials, and connection options stay in your own configuration.
- Is handcraftedinthealps/elasticsearch-dsl actively maintained?
- It has recent releases, including releases in June 2025, and active maintainers such as alexander-schranz and hkulekci. However, it is a fork of a fork with low star and dependent counts, so you are effectively the only consumer shaping its roadmap. Budget for occasionally patching or vendoring the package if an upstream fix is needed.
- What are the alternatives to this package for building Elasticsearch queries in PHP?
- You can hand-assemble associative arrays, use the official elasticsearch-php client directly, or stay on the original ongr/elasticsearch-dsl that this project forks. There is no Laravel-native alternative offering a query-object DSL, so most Laravel projects choose between this package and raw arrays. Raw arrays are simpler but harder to test, reuse, and compose.
- What should I do when the DSL does not support a query type or aggregation parameter?
- The DSL inevitably lags the Elasticsearch API, so new query types and aggregation options may not be modeled yet. Plan an escape hatch and pass raw arrays for those specific clauses while keeping typed objects elsewhere in the same request body. Treat these fallbacks as expected rather than a failure of the package.
Weaver
How can I help you explore Laravel packages today?