Upgrade Guide (v1 → v2)

v2 adds OpenSearch support alongside Elasticsearch and hardens the query builder. It is a major release with breaking changes — most upgrades are a config/env update plus a couple of API adjustments.

Overview

• New: OpenSearch driver, selectable via config (basic-auth, API key, and AWS SigV4).
• New: multi-host clusters, driver-appropriate.
• Changed: environment variables renamed ELASTICSEARCH_* → SEARCH_*.
• Changed: ConnectionInterface now exposes operations instead of the raw client.
• Changed: BridgeBuilder::all() signature.
• Removed: from / to range operators.
• Hardened: invalid operators/clauses now throw; bool clauses always render as arrays.

1. Rename environment variables

All connection env vars were renamed to a backend-neutral SEARCH_* prefix. Update your .env and any deployment configs:

v1	v2
ELASTICSEARCH_HOST	SEARCH_HOST
ELASTICSEARCH_AUTH_METHOD	SEARCH_AUTH_METHOD
ELASTICSEARCH_USERNAME	SEARCH_USERNAME
ELASTICSEARCH_PASSWORD	SEARCH_PASSWORD
ELASTICSEARCH_API_KEY	SEARCH_API_KEY
ELASTICSEARCH_VERIFY_SSL	SEARCH_VERIFY_SSL
ELASTICSEARCH_SSL_CERT	SEARCH_SSL_CERT
(new)	SEARCH_DRIVER (elasticsearch default)
(new)	SEARCH_AWS_REGION / SEARCH_AWS_SERVICE (SigV4)

Re-publish the config to pick up the new keys (back up any customizations first):

php artisan vendor:publish --tag="elastic-bridge-config" --force

There is no fallback to the old names — the old variables are ignored in v2.

2. ConnectionInterface changed

If you bind a custom connection, the contract changed. getClient(): Client was removed in favor of driver-agnostic operations:

interface ConnectionInterface
{
    public function search(array $params): array;
    public function count(array $params): array;
    public function index(array $params): array;
    public function update(array $params): bool;
}

The built-in ElasticConnection and OpenSearchConnection still expose a concrete getClient() for advanced use, but it is no longer part of the interface. If you didn't implement ConnectionInterface yourself, no action is needed.

3. all() signature

The builder's all() gained a page-size parameter and is now a bounded first page (it never requested the whole index — v1's behavior was already a single page, and the unbounded variant that could exceed max_result_window was removed):

// v1
public function all(array $columns = ['*'])

// v2
public function all(int $perPage = 15, array $columns = ['*'])

If you called ->all(['price', 'name']) on the builder, pass the page size first:

->all(15, ['price', 'name']);

The static Model::all(int $perPage = 15) is unchanged.

4. from / to range operators removed

Elasticsearch removed from/to from the range query in 7.x. Use gt/gte/lt/lte:

// v1 (no longer valid — throws InvalidQuery)
->range('price', 'from', 50)

// v2
->range('price', 'gte', 50)

Invalid range/order operators now throw Lacasera\ElasticBridge\Exceptions\InvalidQuery instead of building a query the cluster would reject.

5. multiMatch() / matchPhrase() now nest under bool

These helpers have no term level of their own, so they now attach themselves as a boolmust clause automatically — drop any preceding asRaw():

// v1
HotelRoom::asRaw()->multiMatch(['a', 'b'], 'hotel')->get();

// v2
HotelRoom::multiMatch(['a', 'b'], 'hotel')->get();

Also note: placing match() directly under asBoolean() now throws InvalidQuery — use mustMatch() / shouldMatch() inside a bool query.

6. Bool clause output is always an array

Chaining multiple clauses of the same type used to produce malformed DSL. In v2 every bool clause renders as an array of clause objects. If you asserted on the exact toQuery() shape in tests, update expectations:

// v1
'must' => ['match' => ['currency' => ['query' => 'usd']]]

// v2
'must' => [ ['match' => ['currency' => ['query' => 'usd']]] ]

7. Aggregation results are instance-scoped

Aggregations are no longer registered as global Collection macros. The retrieval syntax is unchanged ($rooms->priceAvg()), but Collection::hasMacro('priceAvg') no longer reflects them. Multiple aggregations on one response now coexist, and results don't leak across requests in long-lived workers.

8. Try OpenSearch (optional)

To switch a project to OpenSearch, set the driver and (for AWS) install the SDK:

SEARCH_DRIVER=opensearch
SEARCH_AUTH_METHOD=sigv4
SEARCH_AWS_REGION=us-east-1

composer require aws/aws-sdk-php   # only for SigV4

See Configuration for the full driver and auth reference.