Installation

ElasticBridge works with both Elasticsearch and OpenSearch. You choose the backend with a single config value — the fluent query API is identical across both.

Requirements

• PHP 8.2 or 8.3
• Laravel 10.x, 11.x, or 12.x
• Elasticsearch 8.x or OpenSearch 2.x

Install

Install the package via composer:

composer require lacasera/elastic-bridge

Publish the config file with:

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

This is the published config file (config/elasticbridge.php):

<?php

return [

    // Driver: 'elasticsearch' (default) or 'opensearch'
    'driver' => env('SEARCH_DRIVER', 'elasticsearch'),

    // Authentication method for the search client
    // Supported: 'basic-auth', 'api-key', 'sigv4' (opensearch only)
    'auth_method' => env('SEARCH_AUTH_METHOD', 'basic-auth'),

    // Search cluster host(s) — comma-separated for a cluster
    // e.g. SEARCH_HOST="https://a:9200,https://b:9200"
    'host' => array_values(array_filter(array_map('trim', explode(
        ',',
        (string) env('SEARCH_HOST', 'https://localhost:9200'),
    )))),

    // Basic auth
    'username' => env('SEARCH_USERNAME', 'elastic'),
    'password' => env('SEARCH_PASSWORD', null),

    // API key auth (used when auth_method = 'api-key')
    'api_key' => env('SEARCH_API_KEY', null),

    // SSL verification — if true, you must provide SEARCH_SSL_CERT
    'verify_ssl' => env('SEARCH_VERIFY_SSL', false),
    'certificate' => env('SEARCH_SSL_CERT', null),

    // AWS SigV4 signing (OpenSearch only, when auth_method = 'sigv4')
    // Requires the aws/aws-sdk-php package.
    'sig_v4' => [
        'region' => env('SEARCH_AWS_REGION'),
        // 'es' (managed) | 'aoss' (serverless)
        'service' => env('SEARCH_AWS_SERVICE', 'es'),
    ],

    // Where bridge files should be generated
    'namespace' => 'App\\Bridges',
];

Environment variables

The connection settings are backend-agnostic and shared by both drivers:

Variable	Purpose
SEARCH_DRIVER	elasticsearch (default) or opensearch
SEARCH_HOST	Host, or comma-separated list for a cluster
SEARCH_AUTH_METHOD	basic-auth, api-key, or sigv4
SEARCH_USERNAME / SEARCH_PASSWORD	Basic auth credentials
SEARCH_API_KEY	API key (when auth_method=api-key)
SEARCH_VERIFY_SSL / SEARCH_SSL_CERT	TLS verification and CA cert path
SEARCH_AWS_REGION / SEARCH_AWS_SERVICE	AWS SigV4 (OpenSearch only)

SEARCH_DRIVER=elasticsearch
SEARCH_HOST=https://localhost:9200
SEARCH_AUTH_METHOD=basic-auth
SEARCH_USERNAME=elastic
SEARCH_PASSWORD=secret

Upgrading from v1?

The environment variables were renamed from ELASTICSEARCH_* to SEARCH_* in v2. See the Upgrade Guide for the full list of changes.

See Configuration for choosing a driver, authentication methods, and running against a cluster.