Elasticsearch Dsl Laravel Package

Product Decisions This Supports

• Search feature scoping and roadmap sizing. The package turns Elasticsearch request bodies (bool logic, filters, nested queries, aggregations, sorting) into composable PHP objects. That gives you a credible estimate of what a release can ship: faceted navigation, relevance tuning, admin filtering, and aggregation-driven dashboards become "write and test query classes" work rather than open-ended JSON string assembly.
• Build vs. buy vs. wrap. The real decision this informs isn't "adopt or not" — it's how deep to couple. Options are: (a) thin internal query-builder wrapper over the official elasticsearch/elasticsearch client, (b) adopt this DSL behind an adapter, (c) adopt it directly in feature code. Option (c) is the one to avoid, and this package's profile is what makes that clear.
• Upgrade and version-ceiling planning. The README's compatibility matrix caps at Elasticsearch ^7.0, yet the release history shows explicit ES 8 support work (8.0.0), kNN search (8.2.0), runtime fields, and parent aggregations (8.3.0). That documentation gap is itself a decision input: someone must validate the 8.x path against the target cluster before it enters a roadmap commitment. Symfography version breadth (2.8–7.x) matters only if you consume the companion Symfony bundle; in Laravel, only the framework-agnostic query library is relevant.
• Dependency-risk posture. A fork of ongr-io/elasticsearch-dsl with ~21 stars and zero dependents is a maintainability question, not a capability question. It justifies a decision to vendor, pin, or isolate — and sets expectations for who patches it when upstream stalls. Recent releases (through mid-2025) mitigate the abandonment risk but don't eliminate it.
• Engineering standards and search quality investment. Object-based queries are unit-testable and reusable across surfaces. That supports funding a search regression suite and code-review conventions for query changes — the kind of work that prevents "relevance silently broke in production" incidents.
• Where it explicitly does not help. It is not a Laravel integration, not a search abstraction over multiple engines, and not a managed-search replacement. Decisions about Algolia/Meilisearch/Typesense, or about Laravel Scout as the developer-facing layer, sit outside this package's scope and shouldn't be framed as either/or with it.

When to Consider This Package

Consider it when:

• Search requirements are genuinely complex — nested bool combinations, multi-clause filters, aggregations for faceting, or query fragments reused across catalog, admin, and API surfaces.
• The team is already on the ongr DSL lineage, or migrating off it, and needs a maintained path with broader Symfony/PHP version support.
• You are on Elasticsearch 6.x or 7.x and the compatibility matrix in the README maps cleanly to your cluster.
• You want Elasticsearch 8 features (kNN, runtime fields) and are prepared to verify the 8.x claim against your cluster with a short spike rather than trust the README table.
• Engineering will isolate the dependency behind an internal interface, add integration tests, and accept responsibility for vendor-patching.
• MIT licensing and zero procurement friction are relevant — no commercial terms, no seat counts.

Look elsewhere when:

• You want a Laravel-native experience: service provider, publishable config, facades, Scout driver, documented Laravel idioms. This package provides none of that; wiring is manual.
• Search is simple — a few match and term queries where the official PHP client plus array literals is less code than learning a DSL.
• Elasticsearch 8+ is a hard requirement and the spike shows the support is partial or the docs stale; the README's ^7.0 ceiling is the conservative read.
• You need production-proven adoption signals — a large dependent ecosystem, third-party tutorials, or answers on Stack Overflow. Twenty-one stars and zero dependents means you are largely on your own.
• You require vendor support, SLAs, or a security-response commitment.
• The roadmap points toward a managed search service, which obsoletes a query-construction library entirely.
• Your team has no appetite for owning a fork, even a lightly patched one.

How to Pitch It (Stakeholders)

To executives: This is a small, MIT-licensed PHP library that lets engineers build Elasticsearch queries as structured, testable objects instead of hand-written JSON. It can shorten delivery on complex search features — faceted filtering, relevance tuning, admin search — and reduce the defect rate that comes from string-built queries. It carries no license cost and no procurement cycle. The caveat is durability: it is a community fork with minimal adoption, so we should treat it as a tactical accelerator, not a platform standard. Recommendation: approve a time-boxed pilot behind an internal adapter, with a documented exit path to the official client, rather than a broad rollout.

To engineering: Use it as a query-construction layer only — it builds request bodies and hands off to whatever transport client you already run; it owns no connections, retries, or cluster state. Installation is Composer-only with a small dependency tree, and the output is a plain array, so it composes with elasticsearch/elasticsearch or a Scout driver without ceremony. The Symfony compatibility story is irrelevant to Laravel — evaluate it as a framework-agnostic library and ignore the companion bundle. Two things need verification before commitment: whether the ES 8 support visible in the release notes is production-ready given the README still tops out at ^7.0, and how much surface area you'd actually use versus wrapping the official client yourselves. Budget a short spike against a real cluster, keep the dependency behind one internal interface, and treat every query class as something worth a unit test.