Scout Laravel Package

Technical Evaluation

Architecture fit

• First-party Laravel package that bolts full-text search onto existing Eloquent models via a Searchable trait and model observers — no new service layer, no rewrite of the read model. For any Laravel monolith or modular monolith, this is the lowest-friction path to search.
• Driver abstraction is the core product value: the application talks to Laravel\Scout\Builder (a fluent, Eloquent-like API), and the engine is a config value. That makes the engine choice a deferrable, reversible decision — the single most important property for a TPM scoping this work.
• Four engine classes are relevant to planning: Algolia (SaaS, turnkey), Meilisearch and Typesense (self-hostable, OSS), plus the bundled Database and Collection engines. Database/Collection are strategically undersold in the README: Collection is a legitimate CI/test double, and Database is a legitimate v1 shipped in production without new infrastructure.
• Sync is event-driven from model lifecycle events, with queue support, which fits the standard Laravel request → queue worker → external system pattern. No CDC pipeline, no dual-write in application code.

Integration feasibility

• Integration surface is small and well-bounded: composer require laravel/scout, publish config, add trait + toSearchableArray() to N models, set driver via env, run scout:import. A single engineer can deliver a working vertical slice in days, not weeks.
• toSearchableArray() is the real design work: it is the denormalization contract. Every relationship flattened into the index is a future reindex trigger.
• Existing changelog shows sustained investment in exactly the areas that bite in production: soft-delete handling, whereIn/whereNotIn, pagination correctness across engines, transaction-commit ordering (afterCommit), custom index names, settings sync, and Laravel 12 / PHP 8.4 support. This is a maintained package on the framework's release cadence, not an abandoned one.

Technical risk

• Engine drift is the dominant technical risk. Feature parity is not uniform: whereIn/whereNotIn, boolean filter formatting, pagination counts, and settings sync have all required engine-specific fixes (multiple Typesense pagination and filter bugs in the 10.11–10.14 range; Algolia client v2/v4 churn). Any filter the team leans on must be validated per engine, not assumed.
• Search payload is a compliance decision, not a technical one. Sending model data to Algolia means PII egress to a third party and data-residency implications. Self-hosted Meilisearch/Typesense keeps data in-VPC; Algolia does not. This must be resolved before the first scout:import, not after.
• Index is a derived, eventually-consistent copy of the database. There is no transactional guarantee between DB commit and index visibility. Staleness windows must be defined and accepted, and a reconciliation path must exist.
• Framework-major coupling. Scout majors track Laravel majors (v8→L9, v9→L10, v10→L11/L12). Search is not independently upgradeable from the framework; it inherits the app's upgrade calendar.
• Cost model is usage-shaped. Algolia bills on records + operations, so index width and write amplification (every save = one index write) directly become a recurring line item. Self-hosted engines convert that to compute + headcount.

Key questions

1. What is the actual retrieval requirement — keyword search only, or typo tolerance, faceting, synonyms, multilingual, relevance tuning, search analytics? This single answer decides Database vs Meilisearch/Typesense vs Algolia.
2. Does any indexed field contain PII or regulated data? If yes, is third-party egress permitted, and in which regions?
3. What is the acceptable index staleness (seconds/minutes/hours) per model, and who owns the alert when it's breached?
4. What is the monthly budget ceiling, and does it scale with record count or is it fixed?
5. Who runs the search infrastructure if self-hosted — is there an existing platform/ops capability, or does this create a new on-call surface?
6. Is search a differentiator (worth a dedicated owner and tuning backlog) or a checkbox feature (buy the boring option)?
7. What are the fallback expectations when the engine is unavailable — degraded DB LIKE search, empty results, or hard error?

Integration Approach

Stack fit

• Requires Laravel 10/11/12-class apps on PHP 8.x. Any modern Laravel codebase is compatible; older apps on legacy Laravel are not and should not be forced onto it.
• Fits the existing queue infrastructure (Redis/SQS/database driver). No new runtime dependency beyond the chosen engine client.
• Read path stays inside the familiar Model::search() idiom, so product engineers don't learn a second query language; the escape hatch is __call() pass-through to the underlying client for engine-specific features.

Migration path

• Phase 0 — abstraction now, engine later. Ship the Searchable trait, toSearchableArray(), and the search endpoint against the Database engine. This proves the UX, the payload shape, and the API contract with zero new infrastructure and zero vendor commitment.
• Phase 1 — swap the driver, not the application. Promote to Meilisearch or Typesense (self-hosted, in-VPC) when typo tolerance/faceting/relevance become requirements. Application code is unchanged; config and scout:import are the only deltas.
• Phase 2 — Algolia only if managed operations, global latency, or search analytics outrank cost and data-residency concerns. Treat this as an explicit buy decision with a contract, not a default.
• Phase 3 — de-risk future swaps by keeping a thin internal SearchService wrapper over Laravel\Scout\Builder so that the ~10% of call sites using engine-specific filters are isolated.

Compatibility

• Pin Scout to the app's Laravel major and treat its upgrades as part of framework upgrades — schedule together, never separately.
• Maintain a conformance test suite that runs the same filter/pagination/sort assertions against every engine in the matrix. This is the only durable defense against engine drift and it makes the "swap the driver" promise real.

Sequencing

1. Confirm engine choice criteria and PII posture (gate — blocks everything).
2. Land trait + toSearchableArray() + Database engine behind the search endpoint; instrument relevance and zero-result rate from day one.
3. Add the conformance test matrix and CI coverage for the Collection engine.
4. Stand up the target engine in staging, run scout:import with tuned chunk size, measure index size, import duration, and query latency.
5. Cut over in production with a versioned/aliased index name (supported via custom index names) so rebuilds are non-destructive.
6. Only then enable queued indexing and turn down the Database fallback to a failure-mode path.

Operational Impact

Maintenance

• Package maintenance burden is low: MIT, first-party, active release cadence, security policy published. The maintenance cost lives in the engine, not the package — schema/settings changes, version upgrades, and capacity of self-hosted Meilisearch/Typesense are owned by us.
• Every change to toSearchableArray() is a reindex event. Budget for a reindex runbook and a scheduled full reindex (e.g. weekly) as routine hygiene, not an incident response.

Support

• Failure ownership splits cleanly: application-side sync failures are ours (queue, observers, payload), engine-side availability is ours (self-hosted) or the vendor's SLA (Algolia). Escalation paths differ entirely by engine choice — decide before launch.
• Search quality complaints ("I can't find X") have no natural owner unless one is assigned. Name a search owner and give them the zero-result and low-CTR dashboards, or relevance will silently rot.

Scaling

• Write amplification is the first scaling constraint: every model save/delete is an index operation. Queue-backed indexing is mandatory above trivial write volume, and index write rate — not query rate — usually hits the first ceiling.
• Queue worker capacity becomes a search dependency. A backlogged queue manifests as stale search results, which users read as "search is broken."
• Query-side scaling is the engine's problem and is largely linear with hardware or plan tier. Algolia scales transparently at a price; self-hosted engines scale with our capacity planning.
• scout:import on large tables is memory- and time-sensitive; chunk size tuning and off-peak scheduling are required operational parameters, not defaults.

Failure modes

• Engine unavailable — search errors or degrades. Needs an explicit decision: fail open to a cheap DB query, return empty with a UI message, or hard-fail. Undecided is the worst option.
• Queue backlog / worker outage — index drifts, then diverges. Mitigation: lag alerting on queue depth plus a periodic reconciliation job comparing DB counts to index counts.
• Silent sync breakage — observer not firing (bulk updates via raw queries, upsert, DB::table() writes bypass Eloquent entirely). This is the most common real-world failure and is invisible without reconciliation. Any bulk-write path must be enumerated and explicitly handled.
• Schema/payload change without reindex — new field simply absent from results; queries against it silently return nothing.
• Partial import — mid-run failure leaves a half-populated index that looks functional. Requires idempotent full-reindex tooling and a post-import verification count.
• Third-party incident (Algolia) or data egress issue — outside our control, inside our SLA to users.

Ramp-up

• Low. A Laravel-fluent engineer is productive in 1–3 days on the package API and 1–2 weeks on a production-grade integration (payload design, queue config, import at scale, fallback behavior).
• The steeper learning curve is not Scout — it is relevance tuning and engine operations for whichever backend is chosen. Budget 3–6 weeks of part-time effort post-launch before search quality is genuinely good, and staff accordingly.
• Overall TPM recommendation: treat Scout as a low-risk, high-leverage adoption with a staged, reversible engine decision. Commit to the abstraction and the Database-engine v1 immediately; defer the managed-vendor commitment until the retrieval requirements, PII posture, and cost ceiling are answered.