Statamic Loupe Laravel Package

Technical Evaluation

Scope of this assessment. This is a baseline evaluation — there is no prior assessment to compare against. The 4.2.0 release notes are two lines and describe behaviour rather than API surface, so the following is built on the reasonable reading that this is a Laravel search-indexing package (Scout-compatible driver over a search backend such as Elasticsearch/OpenSearch or Meilisearch). That assumption is the single largest source of uncertainty here and should be confirmed before committing.

Architecture fit. The package occupies the layer between Eloquent models (via Scout's Searchable trait / engine contract) and the search backend. Both 4.2.0 items reduce glue code we would otherwise own:

• "Keep index searchable while it's being updated" — implies zero-downtime reindex via temp index + alias swap (or backend equivalent). This is the classic thing teams hand-roll badly; if the package now owns it, that's a genuine reduction in bespoke infrastructure.
• "Use the configured primary key consistently" — implies the index document _id now derives from the configured Scout key rather than an implicit id. This closes a real class of bug for models with UUIDs, non-id primary keys, or custom getScoutKey().

Net: this is a small release that removes two common footguns. Attractive, but the second item is a behaviour change even though it's shipped as a minor.

Integration feasibility. Standard Laravel package shape: Composer require, publish config, register the engine/driver, add the trait, define index mappings. No exotic runtime requirements beyond a queue driver (Redis/SQS/database) and a reachable backend. A spike should be achievable in 1–2 days; a production rollout with a reindex is a 1–2 sprint-week effort including staging validation.

Technical risk. Low-to-moderate, concentrated in two places:

1. Primary-key semantics. If any existing deployment indexed documents under id and the model's configured key differs, 4.2.0 will write documents under a different _id. Old documents are not deleted by that change — you get duplicates and stale results unless the index is rebuilt. Any code or dashboard reading _id directly, or joined on it, is affected. Greenfield adoption carries none of this risk; brownfield upgrade carries all of it.
2. Zero-downtime depends on the backend. Alias/swap semantics need backend support and elevated cluster privileges (create index, manage aliases, delete index). Teams on managed backends with locked-down IAM roles can find the "zero-downtime" path blocked at the infrastructure layer, which is a procurement/ops conversation, not a code one. Dual-index reindex also transiently doubles index storage.

Key questions to resolve before approval.

• Which search backend and version is in scope, and does it support aliases/index swap?
• Does the package own alias lifecycle (create/swap/cleanup), or do we?
• What is the documented configuration for the primary key, and does any model override getScoutKey() / searchableAs()?
• Is this a breaking-by-behaviour change for brownfield users? Is a full reindex mandated in the upgrade notes?
• What are the PHP / Laravel / Scout version constraints, and what's the support policy for the previous minor?
• Do we have cluster permissions to create and swap aliases, and who grants them?
• Is a full reindex still required after every mapping change, and is that documented with a runbook?

Integration Approach

Stack fit. Targets Laravel 9–11-era conventions with Scout and a queue worker. Fits our stack if we're already Scout-shaped (Searchable models, index classes, scout:import in deploy). If we aren't, this package is the smaller half of the decision — adopting Scout itself is the real commitment.

Migration path. Treat 4.2.0 as the version we adopt, not something we upgrade into mid-flight, unless a Scout-based index already exists:

• Isolated branch, bump the constraint, publish and diff the config against current settings.
• Run the full test suite plus any search-relevance smoke tests; add assertions that document _id equals the configured key.
• Staging reindex with the swap enabled; compare document counts pre/post and spot-check relevance on a fixed query set.
• Production: reindex during a low-traffic window, watch queue depth and backend CPU, then swap.

If an index already exists under the old key semantics, budget for a full rebuild rather than an in-place migration.

Compatibility. Verify the package's declared matrix against our Laravel/PHP versions, Scout major, and the backend's client library. Watch for: required PHP extensions, whether the zero-downtime path is opt-in via config or automatic (automatic changes the blast radius of a patch bump), and whether searchable() scoping behaves identically during a swap.

Sequencing.

1. Confirm the package identity, backend target, and support matrix (closes the assumption above).
2. Spike: install, define one index, import a representative slice, verify _id mapping.
3. Grant/verify backend index-and-alias privileges.
4. Staging reindex + swap rehearsal, including a deliberate failure to test rollback.
5. Production rollout with rollback pinned to the previous constraint and the previous index left intact until verified.

Operational Impact

Maintenance. Small, focused releases with low churn — a healthy signal. Our ongoing burden is config drift and index mapping ownership, not package upgrades. Budget a recurring line item for reindex operations whenever mappings change; that cost exists with or without this package, but 4.2.0 makes it safer rather than cheaper.

Support. Open-source, community-supported, no SLA. Escalation is GitHub issues. That means we need an internal runbook for reindex and a documented degradation path for search outages — a database-backed fallback query, or Scout's database engine behind a feature flag, is worth having regardless of which package we pick.

Scaling. Reindex throughput is queue-bound: size worker concurrency against documents-per-second measured in staging, not guessed. Transient storage doubles during a dual-index window — relevant for large indices and for backends billed on storage. The primary-key fix is a scaling win in a quieter way: fewer orphaned and duplicate documents means fewer "why is search wrong" incidents at volume.

Failure modes.

• Partial reindex interrupted mid-run → stale or duplicated documents served until a clean rebuild.
• Alias swap fails or privileges are missing → split-brain reads across two indices, or a hard failure during deploy.
• Key mismatch on brownfield upgrade → silently orphaned documents under the old _id; search results degrade with no error surfaced.
• Mapping conflict on reindex → job failures that look like queue problems rather than schema problems.
• Inconsistency window persists: "searchable while updating" concerns the index, not the write path — newly saved models still become searchable only after the batch/refresh interval. Product expectations should be set accordingly.

Ramp-up. A mid-level Laravel developer is productive in about a day. Independent ownership of the alias lifecycle, reindex runbook, and rollback procedure is roughly a week, and that knowledge should not sit with one person. Onboarding material needs the index naming convention, alias convention, reindex procedure, and the fallback query path documented before this goes to production.