jsq/amazon-es-php

Support for using IAM authentication with the official Elasticsearch PHP client

0.3.0 2019-07-20 01:13 UTC

Requires

• aws/aws-sdk-php: ^3.0
• elasticsearch/elasticsearch: ^2.1|^5.0|^6.0|^7.0

Requires (Dev)

• phpunit/phpunit: ^4.8.35|^5.4.0|^6.0.0|^7.0.0|^8.0.0

Apache-2.0

• Jonathan Eskew

• client
• search
• elasticsearch
• aws
• iam

README

NB: SignatureV4 support is built into the Opensearch-PHP client (opensearch-project/opensearch-php) as of version 2.0.1. If you are using the Opensearch-PHP client, you do not need to use this library.

This package provides a signing handler for use with the official Elasticsearch-PHP client (elasticsearch/elasticsearch). By default, the handler will load AWS credentials from the environment and send requestsusing a RingPHP cURL handler.

The search library package must be installed separately. The documentation below will use Elasticsearch-PHP in the examples, but both libraries should be pretty identical.

Basic Usage

Instances of Aws\ElasticsearchService\ElasticsearchPhpHandler are callables that fulfill Elasticsearch-PHP's handler contract. They can be passed to Elasticsearch\ClientBuilder's setHandler method:

use Aws\ElasticsearchService\ElasticsearchPhpHandler;
use Elasticsearch\ClientBuilder;

// Create a handler (with the region of your Amazon Elasticsearch Service domain)
$handler = new ElasticsearchPhpHandler('us-west-2');

// Use this handler to create an Elasticsearch-PHP client
$client = ClientBuilder::create()
    ->setHandler($handler)
    ->setHosts(['https://search-foo-3gn4utxfus5cqpn89go4z5lbsm.us-west-2.es.amazonaws.com:443'])
    ->build();

// Use the client as you normally would
$client->index([
    'index' => $index,
    'type' => $type,
    'id' => $id,
    'body' => [$key => $value]
]);

Using custom credentials

By default, the handler will attempt to source credentials from the environment as described in the AWS SDK for PHP documentation. To use custom credentials, pass in a credential provider:

use Aws\Credentials\CredentialProvider;
use Aws\Credentials\Credentials;
use Aws\ElasticsearchService\ElasticsearchPhpHandler;

$provider = CredentialProvider::fromCredentials(
    new Credentials('foo', 'bar', 'baz')
);

$handler = new ElasticsearchPhpHandler('us-west-2', $provider);

Using a custom HTTP handler

By default, the handler will use Elasticsearch\ClientBuilder::defaultHandler() to dispatch HTTP requests, but this is customizable via an optional constructor parameter. For example, this repository's tests use a custom handler to mock network traffic:

class ElasticsearchPhpHandlerTest extends \PHPUnit_Framework_TestCase
{
    public function testSignsRequestsPassedToHandler()
    {
        $toWrap = function (array $ringRequest) {
            $this->assertArrayHasKey('X-Amz-Date', $ringRequest['headers']);
            $this->assertArrayHasKey('Authorization', $ringRequest['headers']);
            $this->assertStringStartsWith(
                'AWS4-HMAC-SHA256 Credential=',
                $ringRequest['headers']['Authorization'][0]
            );

            return $this->getGenericResponse();
        };
        $handler = new ElasticsearchPhpHandler('us-west-2', null, $toWrap);

        $client = \Elasticsearch\ClientBuilder::create()
            ->setHandler($handler)
            ->build();

        $client->get([
            'index' => 'index',
            'type' => 'type',
            'id' => 'id',
        ]);
    }
    ...
}

Installation

Composer

composer require jsq/amazon-es-php elasticsearch/elasticsearch:"<8.0"

or

composer require jsq/amazon-es-php opensearch-project/opensearch-php