Configuration

ElasticBridge speaks to a search cluster through a driver. The package figures out how each backend expects to be configured — you just supply the connection settings, and the same fluent API works either way.

Choosing a driver

Set the driver with SEARCH_DRIVER (or the driver key in config/elasticbridge.php):

# Elasticsearch (default)
SEARCH_DRIVER=elasticsearch

# OpenSearch
SEARCH_DRIVER=opensearch

• elasticsearch — uses the official elasticsearch/elasticsearch client (installed by default).
• opensearch — uses opensearch-project/opensearch-php (installed by default).

An unknown driver throws an InvalidArgumentException at resolve time.

Authentication

The SEARCH_AUTH_METHOD value selects how the client authenticates. All three methods reuse the same shared credential keys.

Basic auth (default)

SEARCH_AUTH_METHOD=basic-auth
SEARCH_USERNAME=elastic
SEARCH_PASSWORD=secret

API key

SEARCH_AUTH_METHOD=api-key
SEARCH_API_KEY=your-api-key

On Elasticsearch this uses the native API key auth. On OpenSearch it is sent as an Authorization: ApiKey <key> header.

AWS SigV4 (OpenSearch only)

For AWS-managed OpenSearch (or OpenSearch Serverless), sign requests with SigV4:

SEARCH_DRIVER=opensearch
SEARCH_AUTH_METHOD=sigv4
SEARCH_AWS_REGION=us-east-1
SEARCH_AWS_SERVICE=es   # 'es' for managed, 'aoss' for serverless

SigV4 requires the AWS SDK, which is an optional dependency — install it only if you use this method:

composer require aws/aws-sdk-php

AWS credentials are resolved from the standard default provider chain (environment variables, ~/.aws/credentials, IAM role, etc.) — they are not config keys. If the SDK is missing or the region is not set, a clear exception is thrown.

TLS / SSL

SEARCH_VERIFY_SSL=true
SEARCH_SSL_CERT=/path/to/http_ca.crt

When SEARCH_VERIFY_SSL=true, a certificate path is required or a MissingEnvException is thrown.

Running against a cluster

SEARCH_HOST accepts a comma-separated list of hosts:

SEARCH_HOST="https://es1:9200,https://es2:9200,https://es3:9200"

How each driver handles multiple hosts differs by design:

• Elasticsearch load-balances across every host with a built-in connection pool (round-robin + dead-node detection + failover).
• OpenSearch uses the first host only — its modern client is single-endpoint by design. Front a multi-node OpenSearch cluster with a managed endpoint or a load balancer for high availability.

Custom connections

Both drivers implement Lacasera\ElasticBridge\Connection\ConnectionInterface, which exposes search(), count(), index(), and update(). You can bind your own implementation in a service provider if you need bespoke transport behavior:

use Lacasera\ElasticBridge\Connection\ConnectionInterface;

$this->app->bind(ConnectionInterface::class, MyConnection::class);