Elasticsearch Laravel Package

Product Decisions This Supports

• Search feature scope and sequencing. The package determines how much search capability your team can ship per sprint. Because it maps Elasticsearch onto the Eloquent query builder you already use, candidate features that were previously "phase 2 at the earliest" — faceted product filtering, fuzzy/typo-tolerant matching, phrase-prefix autocomplete, geo-distance filtering, aggregations for analytics dashboards — become plausibly shippable in a single iteration. Use this to justify pulling search forward on the roadmap rather than deferring to a dedicated search squad.
• Build vs. buy on the data-access layer. The realistic alternative is not "no Elasticsearch" but "hand-rolled repository/service layer over elasticsearch-php." That is typically several weeks of engineering plus permanent maintenance for query-building, pagination, chunking, index blueprints/migrations, and cross-store relationships. Adoption is a defensible buy decision: you take on a dependency instead of a subsystem.
• Whether Elasticsearch is a primary store or a read model. The package supports full CRUD (create, update, delete, pagination, chunking) and Eloquent relationships both ES→ES and ES→SQL. That makes "Elasticsearch as the system of record for logs, events, clickstream, and audit trails" a legitimate architectural option rather than an exotic one — which changes retention, backup, and compliance requirements you must plan for.
• Staffing and hiring assumptions. Choosing this package is partly a decision to not hire Elasticsearch/DSL specialists. Laravel developers write whereMatch, searchPhrasePrefix, whereGeoDistance, whereFuzzy, and with('user') instead of hand-authored query DSL. Model this in the roadmap as reduced onboarding time and eliminated single-person dependency on a search expert.
• Index lifecycle as product-owned schema. Blueprint-based migrations bring index definitions into the same review-and-deploy workflow as database schema. That lets product and platform agree on field mappings, analyzers, and reindex procedures as versioned changes rather than ad-hoc ops tickets — a meaningful release-safety improvement.
• Log/analytics product decisions. Time-windowed queries over created_at, aggregation queries, group-by/distinct, and geo queries mean you can green-light internal observability tooling and customer-facing analytics from the same model layer, avoiding a separate BI vendor evaluation for early-stage needs.
• The Scout question. For teams considering Laravel Scout, the trade-off is explicit: Scout treats Elasticsearch as a search index bolted onto SQL models, while this package treats ES as a queryable, writable datastore. Decide which mental model matches your product; if you only need "search my SQL models," the maintainer's sibling package ElasticLens is the narrower, lower-blast-radius choice.

When to Consider This Package

Consider it when:

• The stack is Laravel 10–13 on PHP 8.3/8.4 and Elasticsearch 8.x — the actively maintained ~5.6 line explicitly targets Laravel 11/12/13 with CI across those versions.
• The team is Laravel-fluent and small; the ergonomic win (Eloquent idioms, no DSL authoring) is the dominant factor.
• You need search and write/analytics semantics in one place: geo queries, fuzzy matching, highlights, aggregations, cross-store relationships.
• You want index definitions as code with a migration path, reviewed like any other schema change.
• You can afford to pin a minor version and own a small amount of upgrade work — v5.0.0 was a near-complete rewrite with genuinely breaking changes (where() switched from match to term, _id deprecated in favor of id, MAX_SIZE replaced by $defaultLimit, IndexBlueprint/AnalyzerBlueprint merged into Blueprint, search options moved to callbacks).
• Search is adjacent to your differentiator rather than the differentiator itself.

Look elsewhere when:

• You only need full-text search over existing SQL models. Use ElasticLens or Laravel Scout. Do not adopt an ORM replacement to solve a search-only problem.
• You need Elasticsearch 7.x or older. Those lines (~1.x) are marked EOL.
• You are on Laravel 9 or earlier. Only LTS-maintained lines exist; you are buying into code that will not track framework releases.
• You require vendor-backed support, an SLA, or a named escalation path. This is an MIT-licensed package with a small maintainer group; there is no commercial support contract.
• Your use case lives in Elasticsearch features the package does not model — ingest pipelines, transforms, ILM policy authoring, snapshot/restore orchestration, ML/anomaly detection, or highly tuned bulk indexing. Drop to the official client for those and keep this package for model-level access.
• You need hard evidence of production adoption. Zero listed dependents is a signal to validate harder: ask for references, read the issue tracker velocity, and confirm the maintainer's release cadence yourself.
• Your architecture is polyglot. If services outside PHP need the same data access, a shared schema/client contract is a better investment than a Laravel-specific ORM.
• You have extreme write throughput or strict latency budgets where you need direct control over connection pooling, bulk sizing, and retry behavior beyond what the config surface exposes.

Regardless of decision: treat the package as swappable. Bind it behind your own repository/query interface so replacing it with the official client is a contained change, not an application-wide rewrite.

How to Pitch It (Stakeholders)

To executives — the one-paragraph version: "We can add real search — typo tolerance, faceted filtering, location-aware results, aggregations, autocomplete — using the Laravel patterns our team already knows, instead of building and maintaining a custom Elasticsearch layer or hiring a search specialist. It's MIT-licensed, so no licensing cost, and it's actively maintained with explicit support for Laravel 11/12/13 on Elasticsearch 8. The trade-off is that it's a community package with a small maintainer group and limited public adoption evidence, so we'll pin the version, keep it behind our own abstraction, and budget a small amount of ongoing upgrade maintenance."

To engineering — the technical case:

• Extends Eloquent rather than replacing it: same model conventions, same query builder feel, plus ES-native methods (searchTerm, searchPhrasePrefix, whereMatch, whereGeoDistance, whereFuzzy) and highlight().
• Models carry $connection = 'elasticsearch', configured as a standard Laravel database connection with node lists, cloud auth, API keys, TLS options, index prefixing, and retry settings — no bespoke bootstrap.
• Supports the full lifecycle you'd otherwise write yourself: create/update/delete, pagination, chunking, distinct/groupBy, aggregation queries, nested queries, dynamic indices, plus relationships both ES→ES and ES→SQL.
• Index schema as code via Blueprint migrations, reviewable in PRs.
• Quality signals to cite: passing test and PHPStan workflows, documented changelog with per-version notes, versioned documentation site, and a CI matrix over PHP 8.3/8.4 × Laravel 11/12/13.
• Known costs to state plainly: v5 is a rewrite with breaking changes — upgrade guide required if you're coming from v4; where() now issues a term query, so whereMatch must be used explicitly for full-text; _id is gone in favor of id; legacy search methods removed in favor of the callback-based SearchOptions.

Risks to name up front, with mitigations:

1. Maintainer concentration / bus factor. Mitigate: pin minor versions, mirror the repo, track release cadence before committing.
2. Low observable adoption (0 dependents). Mitigate: run a spike against your real query workload before committing; validate pagination, aggregation, and reindex paths specifically.
3. Breaking-change velocity between majors. Mitigate: the abstraction boundary, plus a standing upgrade ticket each Laravel major.
4. Scope creep into unsupported ES features. Mitigate: document the official-client escape hatch for pipelines, ILM, and transforms.

Recommended next step: a two-week, timeboxed spike on one real search surface (product catalog or log search) with the abstraction boundary in place from day one. Success criteria: the target feature ships without DSL hand-authoring, latency and result quality meet the bar, and the fallback to elasticsearch-php remains a contained change.