Connectingedit

This page contains the information you need to connect and use the Client with Elasticsearch.

On this page

Authenticationedit

This section contains code snippets to show you how to connect to various Elasticsearch providers.

Elastic Cloudedit

You can connect to Elastic Cloud using Basic authentication:

$client = ClientBuilder::create()
   ->setElasticCloudId('<cloud-id>')
   ->setBasicAuthentication('<username>', '<password>')
   ->build();

Where <cloud-id> is reported in the Deployment UI, and <username>, <password> are generated when you deploy a new cloud instance. You need to store the <username> and <password> since they will not be available via UI.

Or using an API key:

$client = ClientBuilder::create()
   ->setElasticCloudId('<cloud-id>')
   ->setApiKey('<id>', '<key>')
   ->build();

Where <id> and <key> are generated when you create a new API key. The API key is equivalent to Base64(<id>:<key>). You need to store the API key since it will not be available via UI.

HTTP Authenticationedit

If your Elasticsearch server is protected by HTTP authentication, you need to provide the credentials to ES-PHP so that requests can be authenticated server-side. Authentication credentials are provided as part of the host array when instantiating the client:

$hosts = [
    'http://user:pass@localhost:9200',       // HTTP Basic Authentication
    'http://user2:pass2@other-host.com:9200' // Different credentials on different host
];

$client = ClientBuilder::create()
                    ->setHosts($hosts)
                    ->build();

Credentials are provided per-host, which allows each host to have their own set of credentials. All requests sent to the cluster use the appropriate credentials depending on the node being talked to.

ApiKey authenticationedit

If your Elasticsearch cluster is secured by API keys as described here, you can use these values to connect the client with your cluster, as illustrated in the following code snippet.

$client = ClientBuilder::create()
                    ->setApiKey('id', 'api_key') 
                    ->build();

SSL encryptionedit

Configuring SSL is a little more complex. You need to identify if your certificate has been signed by a public Certificate Authority (CA), or if it is a self-signed certificate.

Public CA Certificatesedit

If your certificate has been signed by a public Certificate Authority and your server has up-to-date root certificates, you only need to use https in the host path. The client automatically verifies SSL certificates:

$hosts = [
    'https://localhost:9200' 
];

$client = ClientBuilder::create()
                    ->setHosts($hosts)
                    ->build();

If your server has out-dated root certificates, you may need to use a certificate bundle. For PHP clients, the best way is to use composer/ca-bundle. Once installed, you need to tell the client to use your certificates instead of the system-wide bundle. To do this, specify the path to verify:

$hosts = ['https://localhost:9200'];
$caBundle = \Composer\CaBundle\CaBundle::getBundledCaBundlePath();

$client = ClientBuilder::create()
                    ->setHosts($hosts)
                    ->setSSLVerification($caBundle)
                    ->build();

Self-signed Certificatesedit

Self-signed certificates are certs that have not been signed by a public CA. They are signed by your own organization. Self-signed certificates are often used for internal purposes, when you can securely spread the root certificate yourself. It should not be used when being exposed to public consumers, since this leaves the client vulnerable to man-in-the-middle attacks.

If you are using a self-signed certificate, you need to provide the certificate to the client. This is the same syntax as specifying a new root bundle, but instead you point to your certificate:

$hosts = ['https://localhost:9200'];
$myCert = 'path/to/cacert.pem';

$client = ClientBuilder::create()
                    ->setHosts($hosts)
                    ->setSSLVerification($myCert)
                    ->build();

Using authentication with SSLedit

It is possible to use HTTP authentication with SSL. Simply specify https in the URI, configure SSL settings as required and provide authentication credentials. For example, this snippet authenticates using Basic HTTP auth and a self-signed certificate:

$hosts = ['https://user:pass@localhost:9200'];
$myCert = 'path/to/cacert.pem';

$client = ClientBuilder::create()
                    ->setHosts($hosts)
                    ->setSSLVerification($myCert)
                    ->build();

Enabling the Compatibility Modeedit

The Elasticsearch server version 8.0 is introducing a new compatibility mode that allows you a smoother upgrade experience from 7 to 8. In a nutshell, you can use the latest 7.x Elasticsearch client with an 8.x Elasticsearch server, giving more room to coordinate the upgrade of your codebase to the next major version.

If you want to leverage this functionality, please make sure that you are using the latest 7.x client and set the environment variable ELASTIC_CLIENT_APIVERSIONING to true. The client is handling the rest internally. For every 8.0 and beyond client, you’re all set! The compatibility mode is enabled by default.

Space encode in URLedit

If you use a space character in an index name, elasticsearch-php converts it into a +, since this space must be encoded in a URL. The same applies to the id and type parameters.

Starting from Elasticsearch 7.4, a + in URL is encoded as %2B by all the REST API functionality. Prior versions handled a + as a single space. If your application requires handling + as a single space you can return to the old behaviour by setting the Elasticsearch system property es.rest.url_plus_as_space to true. You can read the Elasticsearch release note for mote information.

Starting from elasticsearch-php 7.17.2, we introduced an environmental variable ELASTIC_CLIENT_URL_PLUS_AS_SPACE that can be used to encode a space using +, setting the variable to true. If ELASTIC_CLIENT_URL_PLUS_AS_SPACE is set to false, a space is encoded using %20 as specified in RFC 3986.

For instance, if you are using a space character in an index name, this will be encoded using a +, default behaviour. If you set ELASTIC_CLIENT_URL_PLUS_AS_SPACE to false the space in the index name will be encoded with %20.

Usageedit

This section is a crash-course overview of the client and its syntax. If you are familiar with Elasticsearch, you’ll notice that the methods are named just like REST endpoints.

You may also notice that the client is configured in a manner that facilitates easy discovery via your IDE. All core actions are available under the $client object (indexing, searching, getting, etc). Index and cluster management are located under the $client->indices() and $client->cluster() objects, respectively.

Indexing a documentedit

In elasticsearch-php, almost everything is configured by associative arrays. The REST endpoint, document and optional parameters - everything is an associative array.

To index a document, we need to specify three pieces of information: index, id and a document body. This is done by constructing an associative array of key:value pairs. The request body is itself an associative array with key:value pairs corresponding to the data in your document:

$params = [
    'index' => 'my_index',
    'id'    => 'my_id',
    'body'  => ['testField' => 'abc']
];

$response = $client->index($params);
print_r($response);

The response that you get back indicates that the document was created in the index that you specified. The response is an associative array containing a decoded version of the JSON that Elasticsearch returns:

Array
(
    [_index] => my_index
    [_type] => _doc
    [_id] => my_id
    [_version] => 1
    [created] => 1
)

Getting a documentedit

Let’s get the document that we just indexed. This returns the document:

$params = [
    'index' => 'my_index',
    'id'    => 'my_id'
];

$response = $client->get($params);
print_r($response);

The response contains metadata such as index, version, and so on as well as a _source field, which is the original document you sent to Elasticsearch.

Array
(
    [_index] => my_index
    [_type] => _doc
    [_id] => my_id
    [_version] => 1
    [found] => 1
    [_source] => Array
        (
            [testField] => abc
        )

)

Searching for a documentedit

Searching is a hallmark of Elasticsearch, so let’s perform a search. We are going to use the match query as a demonstration:

$params = [
    'index' => 'my_index',
    'body'  => [
        'query' => [
            'match' => [
                'testField' => 'abc'
            ]
        ]
    ]
];

$response = $client->search($params);
print_r($response);

The response here is different from the previous ones. You can see metadata (took, timed_out, etc.) and an array named hits. This represents your search results. Inside of hits is another array named hits, which contains individual search results:

Array
(
    [took] => 1
    [timed_out] =>
    [_shards] => Array
        (
            [total] => 5
            [successful] => 5
            [failed] => 0
        )

    [hits] => Array
        (
            [total] => 1
            [max_score] => 0.30685282
            [hits] => Array
                (
                    [0] => Array
                        (
                            [_index] => my_index
                            [_type] => _doc
                            [_id] => my_id
                            [_score] => 0.30685282
                            [_source] => Array
                                (
                                    [testField] => abc
                                )
                        )
                )
        )
)

Deleting a documentedit

Alright, let’s go ahead and delete the document that we added previously:

$params = [
    'index' => 'my_index',
    'id'    => 'my_id'
];

$response = $client->delete($params);
print_r($response);

This syntax is identical to the get syntax. The only difference is the operation: delete instead of get. The response confirms the document is deleted:

Array
(
    [found] => 1
    [_index] => my_index
    [_type] => _doc
    [_id] => my_id
    [_version] => 2
)

Deleting an indexedit

Due to the dynamic nature of Elasticsearch, the first document you added automatically built an index with some default settings. Delete that index and specify your own settings later:

$deleteParams = [
    'index' => 'my_index'
];
$response = $client->indices()->delete($deleteParams);
print_r($response);

The response:

Array
(
    [acknowledged] => 1
)

Creating an indexedit

Now that you are starting fresh (no data or index), add a new index with custom settings:

$params = [
    'index' => 'my_index',
    'body' => [
        'settings' => [
            'number_of_shards' => 2,
            'number_of_replicas' => 0
        ]
    ]
];

$response = $client->indices()->create($params);
print_r($response);

Elasticsearch now creates that index with your chosen settings and return an acknowledgement:

Array
(
    [acknowledged] => 1
)