OpenSearch Driver

Introduction

Note: This driver is only available with Kipchak Enterprise.

The OpenSearch Driver provides a configured OpenSearch PHP client for Kipchak applications. It supports multiple connections and all common deployment topologies.

Key features include:

• Multiple Connections: Configure separate OpenSearch clusters per use case.
• Topology Support: Single-node, cluster, managed services, and serverless.
• Auth Options: Basic, API key, bearer token, and SigV4 (AWS/OpenSearch Serverless).

Installation

To install this driver, you need to access the Enterprise Composer repository at https://php.pkgs.1x.ax/.

If you have an enterprise license, please contact your account representative for access.

composer require kipchak/driver-opensearch

Initialise the Driver

Add the following line to your drivers/drivers.php file:

\Kipchak\Driver\OpenSearch\OpenSearch::initialise($container);

Configuration

Create a config file named kipchak.opensearch.php in your project's config directory.

Connection Settings

Define connections in the connections array. Each key (e.g., default, analytics) is a connection name.

Common connection settings:

• hosts: List of hosts (each host may include host, port, scheme, user, pass).
• host: Single host string (e.g. http://localhost:9200) if you do not want hosts.
• auth: Authentication settings (see below).
• ssl: SSL settings.
• options: Client-level options (retries and connection params).
• client_builder: Optional callable to override/extend the client builder.

Authentication settings:

• auth.type: basic, api_key, bearer, or sigv4.
• auth.username / auth.password: Basic auth credentials.
• auth.api_key: API key value.
• auth.token: Bearer token.
• auth.access_key / auth.secret_key / auth.session_token: SigV4 credentials.
• auth.region: SigV4 region.
• auth.service: SigV4 service (es for managed OpenSearch, aoss for serverless).

SSL settings:

• ssl.verify: true, false, or a path to a CA bundle.
• ssl.ca_bundle: Optional CA bundle path.

Options:

• options.retries: Retry count for failed requests.
• options.connection_params: Low-level connection parameters passed to the client.

Topology-Specific Settings

Single-Node

Use a single host entry.

Required:

• hosts with one entry, or host string.

Cluster

Provide multiple hosts for round-robin and failover.

Required:

• hosts with multiple entries.

Managed OpenSearch

Use basic auth or SigV4.

Required:

• auth.type: basic or sigv4.
• auth.region and auth.service if using SigV4.

Serverless (OpenSearch Serverless)

Use SigV4 with service aoss.

Required:

• auth.type: sigv4
• auth.service: aoss

Example Configuration

<?php

use function Kipchak\Core\env;

return [
    'connections' => [
        'default' => [
            'hosts' => [
                [
                    'host' => env('OPENSEARCH_HOST', 'opensearch'),
                    'port' => getenv('OPENSEARCH_PORT') !== false ? (int) getenv('OPENSEARCH_PORT') : 9200,
                    'scheme' => env('OPENSEARCH_SCHEME', 'http'),
                ],
            ],
            'auth' => [
                'type' => env('OPENSEARCH_AUTH_TYPE', 'basic'),
                'username' => env('OPENSEARCH_USER', 'admin'),
                'password' => env('OPENSEARCH_PASSWORD', 'admin'),
                'api_key' => env('OPENSEARCH_API_KEY', ''),
                'token' => env('OPENSEARCH_BEARER_TOKEN', ''),
                'access_key' => env('OPENSEARCH_AWS_ACCESS_KEY', ''),
                'secret_key' => env('OPENSEARCH_AWS_SECRET_KEY', ''),
                'session_token' => env('OPENSEARCH_AWS_SESSION_TOKEN', ''),
                'region' => env('OPENSEARCH_AWS_REGION', ''),
                'service' => env('OPENSEARCH_AWS_SERVICE', 'es'),
            ],
            'ssl' => [
                'verify' => env('OPENSEARCH_SSL_VERIFY', true),
                'ca_bundle' => env('OPENSEARCH_CA_BUNDLE', null),
            ],
            'options' => [
                'retries' => getenv('OPENSEARCH_RETRIES') !== false ? (int) getenv('OPENSEARCH_RETRIES') : 2,
                'connection_params' => [],
            ],
        ],
    ],
];

Usage

Code Example

<?php

use Kipchak\Driver\OpenSearch\OpenSearch;

$client = OpenSearch::get('default');
$info = $client->info();

Notes

• SigV4 requires aws/aws-sdk-php to be installed.
• Use client_builder for advanced customization beyond these config options.

Source

The source code for this driver is hosted internally.