Weave Code
Opensearch Scout Driver Laravel Package
directorytree/opensearch-scout-driver
An OpenSearch driver for Laravel Scout that indexes, deletes, flushes, and searches your models through the configured OpenSearch client. Includes publishable client and Scout configs, optional document refreshing, and cursor pagination for deep, stable sorts.
OpenSearch driver for Laravel Scout
Frequently asked questions about Opensearch Scout Driver
- How do I install the OpenSearch driver for Laravel Scout?
- Run composer require directorytree/opensearch-scout-driver, then set SCOUT_DRIVER=opensearch (or change the driver key in config/scout.php). Publish the Scout config if you have not already, then publish the OpenSearch client config and the OpenSearch Scout config using their respective service providers. Finally, point OPENSEARCH_HOST at your cluster. A working local index is typically achievable in well under a day.
- How do I configure the OpenSearch connection used by the Scout driver?
- Connection details live in config/opensearch-client.php, published by DirectoryTree\OpenSearchClient\OpenSearchClientServiceProvider. You set a default connection via OPENSEARCH_CONNECTION and list hosts under the connections array, for example OPENSESARCH_HOST=localhost:9200. Driver-specific options, such as refresh_documents, are published to config/opensearch-scout.php. The client layer owns credentials, transport, retries, and timeouts, so vet it separately from the driver.
- Does this package support AWS SigV4 or IAM authentication for Amazon OpenSearch Service?
- SigV4/IAM request signing is not documented in the README, so treat it as unresolved until you verify it. The underlying directorytree/opensearch-client handles credentials and transport, which is where signing would have to live. If it does not sign requests, you will need signing middleware, a custom transport, or an IAM-authenticated proxy. Resolve this in a spike rather than discovering it in staging.
- Which Laravel, Scout, PHP, and OpenSearch versions does this driver support?
- The README does not publish a complete compatibility matrix. Check composer.json constraints and the CI workflow (run-tests.yml) to see what is actually covered by tests. Do this before committing, because the supported Laravel, Scout, PHP, OpenSearch, and client versions drive your upgrade path. An untested combination is a real risk, not a formality.
- How does cursor pagination work in this OpenSearch Scout driver?
- The driver supports cursorPaginate for deep pagination, backed by OpenSearch search_after. This requires at least one explicit sort in your query, and you should use a unique indexed tie-breaker such as the model key as the final sort. Without that, deep pagination can silently skip or duplicate documents. Treat the sort contract as part of your query code, not an optional detail.
- What does the refresh_documents option do?
- It is a driver setting published to config/opensearch-scout.php and controlled by OPENSEARCH_SCOUT_REFRESH_DOCUMENTS, defaulting to false. When enabled, the driver refreshes documents so writes become visible to searches more immediately. That is useful in development and test suites but can add overhead in production, so decide deliberately per environment.
- Does the driver report partial bulk indexing failures per document?
- The README does not document how bulk responses are handled. You need to check the Engine implementation to see whether partial failures are surfaced per document or treated as an all-or-nothing bulk request. This matters for queue-driven indexing and scout:import, where a silent partial failure leaves your index incomplete. Validate it with a deliberate failing-document test.
- Is this a drop-in replacement for the Elasticsearch Scout driver?
- It is an adapter that implements Laravel Scout's engine contract, so adoption is a driver swap rather than a rewrite: Searchable models, observers, search(), where() constraints, and pagination stay in your application code. The package is not a search platform, though. Index and alias management, mapping design, reindex orchestration, synonyms, and relevance tuning are not included and remain your responsibility.
- Does the driver support soft deletes, shouldBeSearchable, and queued indexing?
- Those are Scout features that flow through the engine contract, but you should verify them explicitly against this Engine implementation rather than assume parity. Test where() operators, soft deletes, shouldBeSearchable(), queue-driven indexing, scout:import and scout:flush, and model updates and deletes. A short integration test suite against a real OpenSearch container is the cheapest way to confirm behavior.
- Is this package production-ready and actively maintained?
- It is a small, early-stage, effectively single-maintainer package with zero dependents and little public usage, so there is limited adversarial testing in the wild. Budget time for reading the source (it is small) and for the possibility of maintaining a fork. Operational risk dominates technical risk here: the driver is cheap, but the cluster, mappings, reindexing, and relevance tuning are expensive and must be owned.
Weaver
How can I help you explore Laravel packages today?