Elastic Migrations Laravel Package

Product Decisions This Supports

• Index schema as code, not tribal knowledge. Every mapping/alias/settings change for an Elasticsearch index becomes a versioned, reviewable artifact that runs identically in dev, staging, and production. That removes the most common cause of "works on my machine" search bugs and the "who changed the analyzer in Kibana?" outage class.
• Feature/roadmap gating for search. Adding new searchable fields, changing analyzers, adding synonym sets, or resplitting an index into new shards becomes a discrete migration with a rollback path. This lets a PM sequence search work into small, shippable increments instead of a risky big-bang reindex tied to a release window.
• Build vs. buy, decided cheaply. The alternative is a bespoke Artisan command + a folder of JSON mapping files + an internal "how we deploy ES" runbook. This package is that, already tested and maintained, under MIT. Choosing it explicitly avoids burning 1–2 sprint-weeks of senior engineering time on internal tooling that no customer will ever see.
• Release/deployment confidence. Because index changes are tracked like DB migrations, releases touching search can be promoted with normal CI/CD gates, and rollback is a known operation rather than an ad-hoc investigation. This directly reduces the blast radius of search-related regressions, which are typically high-visibility to users.
• Multi-environment / multi-tenant readiness. Sharing index schema across environments and (with per-tenant index naming) across tenants becomes a repeatable pattern — relevant if the roadmap includes per-customer search isolation, environment parity for QA, or spin-up/tear-down of ephemeral preview environments.
• Zero-migration, low-lock-in adoption. It's a thin, opt-in layer; it does not force an ORM rewrite or a specific Elasticsearch client abstraction. That keeps the option value of the decision high and the cost of reversing it low.

When to Consider This Package

Adopt when all or most of the following hold:

• The product runs Laravel and uses Elasticsearch directly or via Scout, and search is a genuine product surface (not a toy autocomplete).
• You have more than one environment (local, CI, staging, prod) and index schema drift has already bitten you, or obviously will.
• Search mapping changes are expected on the roadmap — new fields, analyzer/tokenizer changes, synonym dictionaries, per-locale indices — rather than being frozen forever.
• The team already accepts migration-style workflows for relational schema, so this is a familiar mental model rather than a new discipline to teach.
• You want the schema in code review, with history, rather than in a wiki page or dashboard.

Look elsewhere or defer when any of these dominate:

• You are not on Laravel. This is Laravel-console-bound; plain PHP, Symfony, or Node services get nothing. Consider elasticsearch-migrations-style tooling in your own stack, or Terraform/Infra-as-Code for index templates managed by platform teams.
• Managed/index-template-first architectures. If your org mandates index templates and ILM managed centrally (Elastic Cloud, platform team ownership), a per-app migration tool duplicates and can conflict with that control plane. Prefer central templates plus a thin app-level bootstrap.
• Zero-reindex-change tolerance. This package helps you organize index changes; it does not eliminate the hard parts. A mapping change that requires a reindex still needs an alias-swap strategy, backfill, and dual-write/read-cutover plan. If the team cannot own that operational pattern, adoption creates risk without mitigating it.
• Very low change frequency. One index, frozen mapping, shipped two years ago — the migration table, config, and extra deploy step are pure overhead.
• Single-maintainer dependency risk is unacceptable. With ~195 stars, 0 dependents recorded, and a sole maintainer model (donations link, no org backing), a regulated or high-availability-critical context may require a vendored fork or internal maintenance commitment before adoption.
• You actually need cross-cluster/replication or per-document-version migration semantics. Out of scope; do not stretch this tool there.

Also verify before committing: compatibility matrix with your Laravel version, PHP version, and Elasticsearch 7 vs 8 (client breaking changes are the usual failure mode), and whether your CI can run a real ES container — these migrations are untestable in earnest without one.

How to Pitch It (Stakeholders)

For executives — one paragraph. Search quality issues are hard to attribute and expensive to diagnose; the most common root cause is that the index schema drifted from what the application expects, because it was last edited by hand in a dashboard. This package lets us manage search index definitions the same way we already manage database changes — versioned, code-reviewed, replicated identically through staging and production, and reversible. It is small, MIT-licensed, and adoptable in days rather than a platform project. The business value is fewer customer-visible search incidents, faster and safer delivery of search features, and no bespoke internal tooling to build or maintain.

For engineering leadership — the substance.

• Problem: index mappings, analyzers, and alias configuration are currently changed manually and inconsistently; there is no authoritative history and no safe rollback. Environment parity for search is assumed, not verified.
• Proposal: adopt babenkoivan/elastic-migrations as the single mechanism for index schema change in Laravel services. Schema lives in the repo, changes ship through the existing pipeline, rollback is a defined command.
• Cost: low — small surface area, MIT, no license negotiation, no vendor relationship, no data-model rewrite. Integration is a Composer dependency plus a config file plus a CI step.
• Explicit non-goals and residual risk: it does not remove reindex operations, does not handle cross-cluster or per-document versioning, and it is a single-maintainer open-source project with a modest contributor base and no organizational sponsor. Mitigation: pin a version, run the migrations against a real Elasticsearch in CI so we are never surprised by an upgrade, and — if search becomes business-critical — budget a small amount of capacity to fork and maintain. That mitigation cost is materially less than continuing to manage index state by hand.
• Decision requested: approve inclusion in the search service for the next release cycle; success measured by indexed schema changes performed via migration only (target: 100%), and zero manual dashboard edits to production indices.

For the engineering team — the pitch in one line. It's php artisan migrate for your Elasticsearch mappings: versioned, shareable across environments, reviewable in PRs — so nobody has to remember what the product index mapping looked like before the last hotfix.