Statamic Loupe Laravel Package

Product Decisions This Supports

• Zero-downtime search schema changes. "Keep index searchable while it's being updated" means reindexing/backfills no longer require a maintenance window or a read-only search experience. PM-relevant consequence: search mapping changes (new filterable fields, analyzer tweaks, synonym sets) become routine sprint work instead of a scheduled operational event with a rollback plan.
• Roadmap sequencing for search quality. Because a full reindex is now cheap operationally, relevance improvements can be shipped incrementally and A/B'd against a live index. This typically unlocks a "search quality" epic that had been deferred behind "search stability."
• Build vs. buy — narrows the case for a bespoke indexing pipeline. The package owns the hard operational mechanics (index lifecycle, atomic swap, live-read during rebuild). Your team still owns mappings, queries, and ranking. That splits the decision cleanly: buy the plumbing, build the relevance.
• Identifier correctness as a first-class capability. "Use the configured primary key consistently" suggests prior versions had code paths that implicitly assumed an id-style key. If your domain uses UUIDs, ULIDs, or composite/string keys (common in multi-tenant SaaS, marketplaces, and sync-from-legacy systems), this release is what makes the package safe to adopt rather than something you patch around.
• Representative use cases. Product catalogs, marketplace listings, per-tenant indexes in multi-tenant apps, documentation/content search, and any feature where "search is stale or down during a deploy" is a visible customer-facing defect.

When to Consider This Package

Adopt when:

• You are on Laravel and already lean on (or are evaluating) Scout-style model indexing rather than hand-rolled indexing jobs.
• Search changes are frequent enough that a reindex maintenance window is a recurring planning tax — or user-visible.
• Your models use non-default primary keys, and you need consistent key handling across indexing, updating, and deleting.
• Your ops capacity is small; you want atomic index switching handled by the library, not a runbook.
• You need search to remain fully available during backfills (e.g. a large catalog re-import).

Look elsewhere when:

• Your search backend already versions indexes natively and hides swap semantics from you (fully managed search SaaS). You would be paying complexity for a solved problem.
• You need ranking/relevance authoring, vector/hybrid search, or query DSL ownership as the primary value — this is infrastructure, not a relevance engine.
• Your dataset reindexes in seconds and a brief read-only window is acceptable; the alias/swap machinery is unearned overhead.
• You cannot own or operate the underlying search cluster, or you need a framework-agnostic indexer shared with non-PHP services.
• You require the package's indexing path to be the single source of truth for writes — dual-write/eventual-consistency tradeoffs need explicit design either way.

Release-specific caveats for 4.2.0: this is a minor release; the notes describe behaviour corrections rather than declared breaking changes. However, "use the configured primary key consistently" implies at least one code path previously derived document IDs differently. Verify that existing index document IDs match what the new version computes before upgrading, and plan a full reindex if any model relies on a custom key. Treat that verification as an upgrade task, not a follow-up.

How to Pitch It (Stakeholders)

For executives: Search infrastructure changes currently require a planned window, which means either customer-visible degradation or after-hours work. This release removes that constraint — the index stays live and searchable while it is rebuilt and swapped. Practically: faster shipping on anything search-adjacent, less release risk, and no new headcount to operate it. The upgrade itself is a minor version with no declared breaking changes; the cost is a verification pass plus one reindex, not a migration project.

For engineering: Small, well-scoped adoption. 4.2.0 is additive in intent — live index rebuild via swap, and consistent primary-key handling throughout the index/update/delete paths. Two things to check before merging: (1) confirm document IDs for models with custom keys match the new derivation, and reindex if they do not; (2) confirm the configured primary key is explicitly set on models where it was previously inferred. Both are configuration and verification, not code changes. The package deliberately does not own query construction or ranking, so it composes with the existing search layer rather than replacing it.

For the product team: Nothing in the user-facing behaviour changes by default. The value is that search-related work stops needing a maintenance window and stops being blocked on non-standard primary keys — both of which shorten the path to search improvements already on the roadmap.

Basis note: this assessment is derived from the 4.2.0 release notes alone; no repository, benchmark, or dependency-audit data was available. Confirm version support, maintainer activity, and backend compatibility before committing to a roadmap dependency.