Weave Code
A Laravel integration for the official OpenSearch PHP client
Frequently asked questions about Opensearch Client
- How do I replace Elasticsearch with OpenSearch in my Laravel app using this package?
- This package wraps the official OpenSearch PHP client, so you can swap Elasticsearch for OpenSearch by updating your Laravel config to point to your OpenSearch endpoint (e.g., `OPENSEARCH_HOST=your-opensearch-domain.us-east-1.es.amazonaws.com`). The API remains identical, so existing queries and mappings transfer directly. For Laravel Scout users, you’ll need to extend the OpenSearch driver or use this package’s facades for a smoother transition.
- Does this package support Laravel Scout for search functionality?
- While this package doesn’t include a full Scout driver, it provides Laravel-friendly facades and service container integration to simplify OpenSearch queries. You can manually extend Scout’s Elasticsearch driver to use this package’s client or build a custom repository pattern. The package focuses on low-level OpenSearch integration, leaving higher-level search logic to your app.
- What Laravel versions are officially supported, and are there breaking changes between versions?
- The package is tested against Laravel 10.x and 11.x (LTS versions) and follows Laravel’s semantic versioning. Breaking changes are rare but may occur if the underlying OpenSearch PHP client updates. Always pin your `directorytree/opensearch-client` version (e.g., `^1.0`) and Laravel to stable releases. Check the changelog for version-specific notes.
- Can I use this package with self-hosted OpenSearch or only AWS OpenSearch Service?
- This package works with any OpenSearch cluster—self-hosted (Docker, Kubernetes), on-premises, or managed services like AWS OpenSearch. Configure your `.env` with the correct `OPENSEARCH_HOST` (e.g., `http://localhost:9200` for local testing or `https://your-cluster.us-east-1.es.amazonaws.com` for AWS). TLS/SSL and authentication (API keys, IAM roles) are configurable via the package’s settings.
- How do I index Eloquent models into OpenSearch for real-time search?
- Use Laravel’s model events (e.g., `saved`, `deleted`) to trigger OpenSearch updates via queued jobs. For example, attach a `saved` event to your `Product` model that pushes data to OpenSearch using the package’s client. Alternatively, create a repository pattern or trait (e.g., `HasOpenSearch`) to abstract indexing logic. For bulk operations, use OpenSearch’s bulk API for efficiency.
- What’s the best way to handle OpenSearch connection failures in production?
- Implement a fallback strategy by wrapping OpenSearch operations in a try-catch block and logging failures. For critical searches, cache results in Redis or Laravel’s cache layer with a short TTL (e.g., 5 minutes) to degrade gracefully. Use Laravel’s queue system to retry failed indexing jobs. Monitor connection health with AWS CloudWatch (for managed services) or custom health checks.
- Does this package support advanced OpenSearch features like geospatial queries or aggregations?
- Yes, the package leverages the official OpenSearch PHP client, so all features—including geospatial queries, aggregations, and security plugins (TLS, fine-grained access control)—are supported. Use the client’s methods directly (e.g., `OpenSearch::geoDistance()`) or chain them via the facade. Refer to the [OpenSearch PHP client docs](https://opensearch.org/docs/latest/clients/php/) for advanced usage.
- How do I configure TLS/SSL and authentication for AWS OpenSearch Service?
- Set `OPENSEARCH_SSL=true` in your `.env` and provide the AWS-signed certificate (e.g., `OPENSEARCH_CA_CERT=/path/to/root-ca.pem`). For authentication, use API keys (`OPENSEARCH_API_KEY=your_key`) or IAM roles if your cluster is configured for AWS authentication. The package automatically handles SSL verification if the CA cert is provided. For self-hosted clusters, use basic auth or custom auth plugins.
- Can I use this package in a Laravel microservice architecture?
- Absolutely. The package is designed for modular use: inject the OpenSearch client via Laravel’s service container or use the facade in any microservice. For distributed systems, consider HTTP clients (e.g., Guzzle) to call OpenSearch directly if you need to bypass Laravel’s container. Queue workers can handle async indexing across services, ensuring consistency.
- What are the performance implications of real-time indexing vs. batch updates?
- Real-time indexing (e.g., via model events) adds minimal latency but may overwhelm OpenSearch under high traffic. For production, use Laravel queues to batch updates (e.g., 100 records per job). Benchmark your workload: bulk API calls are faster for large datasets, while real-time syncs suit low-volume, high-priority data. Monitor OpenSearch’s cluster health and adjust shards/replicas as needed.
Weaver
How can I help you explore Laravel packages today?