Opensearch Scout Driver Laravel Package

Product Decisions This Supports

• Search backend selection (build vs. buy vs. adopt). The package makes "which search engine" a driver configuration choice rather than an application rewrite: existing Searchable models, ::search() calls, where() filters, and pagination keep working while the backend moves to OpenSearch. That lowers the switching cost of the decision itself and keeps the decision reversible. It is the enabler for choosing OpenSearch specifically — self-hosted, or Amazon OpenSearch Service — over Algolia, Meilisearch, Typesense, or Elasticsearch.

• Licensing and vendor posture. OpenSearch is Apache 2.0 and self-hostable. This supports a deliberate move away from usage-priced search SaaS (Algolia's per-record model) or license-encumbered Elasticsearch (SSPL / Elastic License) without a visible change to product-facing search behavior.

• Cloud, sovereignty, and compliance constraints. Relevant wherever search must live inside a VPC, inside an AWS account, or in a specific region for data-residency reasons — cases where a managed third-party index is a compliance blocker rather than a convenience.

• Roadmap sequencing for search. If search today is Postgres LIKE/full-text or Scout's database driver, this package defines the "swap in a real search engine" milestone as a small, reversible increment. Relevance tuning, faceting, typo tolerance, synonyms, and index lifecycle management become separately scoped follow-on work instead of one big-bang migration.

• Feature scoping — what becomes achievable. Signals the capability step-change once adopted: relevance ranking, fuzzy matching, filterable/sortable attributes, and deep pagination via cursorPaginate/search_after. It also marks the boundary of what stays in-house: search UI/UX, query analytics, synonym curation, merchandising rules.

• Platform standardization. For teams already running OpenSearch for logs or observability, this consolidates onto one search technology and one ops skillset, reducing the number of distinct systems the org operates and staffs.

When to Consider This Package

Adopt when all of these hold:

• The application is Laravel and already uses — or is willing to adopt — Laravel Scout as its search abstraction. This is an adapter, not a search framework.
• You have, or plan to have, a running OpenSearch cluster (self-managed or Amazon OpenSearch Service) and someone owns its operations: index mappings, shard sizing, upgrades, backups, and reindex procedures.
• You need capabilities Scout's database driver cannot deliver — relevance ranking, fuzzy matching, facets/filters, or index volumes where SQL full-text becomes the bottleneck.
• Preserving the option to change search backends later without touching model code has real value, i.e. Scout's abstraction is earning its keep in your architecture.
• Search needs are a small number of well-understood surfaces, so a feature-flagged pilot on one of them is a realistic first step.

Look elsewhere or proceed with caution when:

• Maturity risk is unacceptable. This is a new, low-adoption, effectively single-maintainer package with zero known dependents. Treat it as a thin, well-scoped adapter — budget for reading the source (it is small) and for the possibility of maintaining a fork.
• You want a managed, zero-ops search product. Algolia, Meilisearch Cloud, or Typesense Cloud remove operational burden this package does not.
• You need Elasticsearch specifically, or advanced OpenSearch capabilities (kNN/vector search, neural queries, ingest pipelines) the driver may not surface. Vet the companion directorytree/opensearch-client package it depends on — that client holds credentials, transport, retries, and timeouts.
• AWS SigV4/IAM authentication is a hard requirement and unproven. The README does not document it. Confirm before committing to Amazon OpenSearch Service as the target.
• You are not on Laravel Scout, or your search needs are simple lookups that Postgres full-text already handles — the added infrastructure is not justified.
• You cannot support an OpenSearch cluster in cost, headcount, or expertise. The driver is the cheap part; the cluster is the expensive part.

How to Pitch It (Stakeholders)

To executives: Search today is constrained by our database. Rather than locking into per-record-priced search SaaS, this package lets us run OpenSearch — open source, self-hostable, and available as a managed AWS service — while keeping our existing Laravel search code largely intact. That means lower marginal cost as the index grows, a credible path to data-residency and VPC compliance, and freedom to change search vendors later without a rewrite. Flag honestly: this is a small, early-stage open-source adapter with one primary maintainer and minimal adoption. The recommendation is a time-boxed pilot on a single low-risk search surface — not org-wide standardization — with an explicit go/no-go on cluster ownership and relevance requirements at the end. The real cost is operational (running the cluster, designing index mappings, owning reindex and backfill), not the PHP integration.

To engineering: It is a Scout driver. Install it, set SCOUT_DRIVER=opensearch, publish the Scout, OpenSearch client, and driver configs, point it at a host — existing Searchable models and search() calls keep working, including cursorPaginate for deep pagination, which requires an explicit stable sort with a unique tie-breaker (e.g. the model key) as the final sort. Effort is dominated by operations and relevance tuning, not glue code: cluster provisioning, index mappings and analyzers, reindex/backfill jobs, and query-time behavior. Because adoption is near zero, run a time-boxed spike: read the Engine implementation and validate the Scout features we actually depend on — where() constraints, pagination, soft deletes, shouldBeSearchable(), queue-driven indexing, scout:import/scout:flush, and partial bulk-failure reporting. Confirm AWS SigV4 auth support and the supported Laravel/Scout/OpenSearch version matrix against composer.json before committing. Roll out behind Scout's driver config so rollback is a one-line environment change.

The ask: Approve a 1–2 week spike on a single, low-risk search surface, delivering a go/no-go recommendation on cluster ownership, relevance requirements, and AWS auth compatibility — with rollback guaranteed by configuration alone.