Weave Code
Opensearch Adapter Laravel Package
directorytree/opensearch-adapter
A PHP adapter for the OpenSearch PHP client that provides document and index managers plus fluent mapping and settings builders for defining fields, analyzers, and custom index configurations.
A PHP adapter for the official OpenSearch PHP client. It provides fluent wrappers for creating and managing documents and indices, letting you define mappings and settings through expressive builders instead of raw arrays.
- DocumentManager and IndexManager built from any
OpenSearch\Client - IndexBlueprint combining Mapping and Settings builders
- Helpers like
keyword(),text(), andobject(), plusfield()for custom or newer field types - Top-level settings groups such as
analysis
Frequently asked questions about Opensearch Adapter
- How do I install directorytree/opensearch-adapter in a Laravel or PHP app?
- Install it with Composer using composer require directorytree/opensearch-adapter. There is no service provider to register and no framework coupling, so Laravel and plain PHP applications wire it the same way. You construct the managers yourself from an existing OpenSearch\Client instance: new DocumentManager($client) and new IndexManager($client). If you want container bindings or config files in Laravel, add them yourself with a small service provider.
- Does directorytree/opensearch-adapter replace the official opensearch-php client?
- No. It is a thin adapter layered on top of the official opensearch-php client, which remains the transport and connection layer. The package adds DocumentManager and IndexManager entry points plus fluent Mapping, Settings, and IndexBlueprint builders so index definitions stop being hand-written arrays. You still bring your own configured OpenSearch\Client, including hosts, credentials, and retry behavior.
- Which PHP and OpenSearch versions does this adapter support?
- The CI matrix covers PHP 8.2 through 8.4, and integration tests run against OpenSearch 2.19.3 and 3.7.0, so it is exercised on both current cluster generations. Because the package has no Laravel service provider or framework dependency, there is no Laravel version constraint to worry about beyond your PHP version. Confirm the pinned opensearch-php client version matches the one already used in your services before adopting.
- How do I create an OpenSearch index with mappings and settings using this package?
- Build a Mapping with helpers such as dynamic(), keyword(), text(), and object(), build a Settings instance with index(), analysis(), or other settings groups, then pass both into an IndexBlueprint and call $indices->create(). For example, an IndexBlueprint('books', $mapping, $settings) creates the index with your shard count, replica count, refresh interval, and field definitions in one call. This replaces the nested associative arrays you would otherwise pass directly to the client's indices()->create() endpoint.
- How do I add a custom or uncommon field type to an OpenSearch mapping?
- Use the field() method on the Mapping builder, passing the field name, the OpenSearch type string, and any extra options. The README example is (new Mapping)->field('embedding', 'custom_vector', ['dimension' => 1536]). That escape hatch means newer or vendor-specific OpenSearch types such as knn_vector, rank_feature, or completion do not require forking the package. The typed helpers like text() and keyword() are conveniences, not a closed list.
- Does this package handle AWS SigV4 or IAM authentication for Amazon OpenSearch?
- No. Authentication, signing, and transport are concerns of the underlying opensearch-php client, not the adapter, so managed-service setups like AWS SigV4 signing or IAM roles must be configured at the client level before you construct the managers. This is a common blocker on managed OpenSearch, so verify your signing story during evaluation. If you cannot produce an authenticated OpenSearch\Client instance, the adapter will not help.
- Does the adapter keep my Eloquent models in sync with OpenSearch automatically?
- No. There is no ORM integration, no model observers, no index-on-save, and no queue-backed reindexing. The package manages indices and documents, but something else has to decide when a document is written or deleted. If your feature assumes the search index tracks Eloquent automatically, budget for a separate sync layer or evaluate a Scout driver instead.
- Can I write aggregations or a typed query DSL with this adapter?
- Only partly. SearchRequest wraps raw query DSL fragments and normalizes request and response objects, so you still hand-write aggregation and query arrays. There are no aggregation builders or typed query objects, and the package does not change how you author queries. What it removes is index, document, and response boilerplate, not query authoring effort.
- How do I test code that uses the OpenSearch adapter without a real cluster?
- The package includes fake testing APIs so you can exercise manager and builder code without a live OpenSearch node, which removes a lot of QA cost. Use them alongside unit tests that assert the mapping and settings arrays your builders produce, since those arrays are the actual contract with the cluster. Keep at least a few integration tests against a real cluster, because fakes that drift from cluster behavior are a classic source of green tests and broken relevance.
- Is directorytree/opensearch-adapter actively maintained, and should we fork it?
- It is a small MIT-licensed package from a single vendor with a very modest install base, so treat the bus factor as the main risk rather than code quality. The surface area is tiny enough to read end to end in an afternoon, which makes forking cheap and the adoption decision reversible. If you depend on it in production, name a maintainer, pin the version, and be prepared to vendor the manager and builder classes while keeping the public API.
Weaver
How can I help you explore Laravel packages today?