configuration.asciidoc

Configuration

Almost every aspect of the client is configurable. The client is built around Pimple a light-weight dependency injection container. Most users will only need to configure a few parameters to suit their needs.

However, since the container also controls all object instantiation, it is possible for users to completely change the internal components used by the client. A user could, for example, write a custom ConnectionPool class and use that instead of the default connection pools that ship with the client

Host Configuration

A common operation will be telling the client what nodes are in your cluster. By default, the client will connect to 'localhost:9200', which obviously doesn’t work in many production environments.

All configurations (both simple parameters and more advanced component-replacement) are injected into the constructor of the client.

The client accepts an array of hosts that you would like to connect to. Each value in the array must be a string (either with or without the port number). SSL can be enabled by prefixing the host with 'https':

$params = array();
$params['hosts'] = array (
    '192.168.1.1:9200',                 // IP + Port
    '192.168.1.2',                      // Just IP
    'mydomain.server.com:9201',         // Domain + Port
    'mydomain2.server.com',             // Just Domain
    'https://localhost',                // SSL to localhost
    'https://192.168.1.3:9200',         // SSL to IP + Port
    'http://user:pass@localhost:9200',  // HTTP Basic Auth
    'https://user:pass@localhost:9200',  // SSL + HTTP Basic Auth
);

$client = new Elasticsearch\Client($params);

This associative array holds all custom configurations that you may want to set. Often, you’ll only need to configure the hosts, but if you need more advanced behavior, read on.

Ignoring exceptions

The library attempts to throw exceptions for common problems. These exceptions match the HTTP response code provided by Elasticsearch. For example, attempting to GET a nonexistent document will throw a MissingDocument404Exception.

Exceptions are a useful and consistent way to deal with problems like missing documents, syntax errors, version conflicts, etc. But sometimes you want to deal with the response body rather than catch exceptions (often useful in test suites).

If you need that behavior, you can configure an ignore parameter. The following setting will ignore the MissingDocument404Exception exception and instead return the JSON provided by Elasticsearch:

$client = new Client();

$params = array(
    'index'  => 'test_missing',
    'type'   => 'test',
    'id'     => 1,
    'ignore' => 404 (1)
);
echo $client->get($params);

> {"_index":"test_missing","_type":"test","_id":"1","found":false}


$params = array(
    'index'  => 'test_missing',
    'type'   => 'test',
    'ignore' => [400, 404] (2)
);
echo $client->get($params);

> No handler found for uri [/test_missing/test/] and method [GET]

1. This will ignore just the 404 missing exception

2. ignore also accepts an array of exceptions to ignore. In this example, the BadRequest400Exception is being ignored

It should be noted that the response is simply a string, which may or may not be encoded as JSON. In the first example, the response body was a complete JSON object which could be decoded. In the second example, it was simply a string.

Since the client has no way of knowing what the exception response will contain, no attempts to decode it are taken.

Providing custom query parameters

Sometimes you need to provide custom query params, such as authentication tokens for a third-party plugin or proxy. All query parameters are white-listed in Elasticsearch-php, which is to protect you from specifying a param which is not accepted by Elasticsearch.

If you need custom parameters, you need to bypass this whitelisting mechanism. To do so, add them to the custom parameter as an array of values:

$getParams = array(
    'index' => 'test',
    'type' => 'test',
    'id' => 1,
    'parent' => 'abc',  // white-listed
    'custom' => array('customToken' => 'abc', 'otherToken' => 123) // user-defined, not white listed, not checked
);
$exists = $client->exists($getParams);

Configuring the Logger

By default, logging in the client is disabled for performance reasons. If you wish to enable logging, simply set the logging parameter to true:

$params = array();
$params['logging'] = true;
$client = new Elasticsearch\Client($params);

​

This will enable logging to a file called elasticsearch.log inside your project directory. The default logging level is WARN. This is a logging level that only describes important events that should probably require action from you.

Often, you’ll want to change the logging location or set the logs file permissions to group writeable. To change these things, simply do the following:

$params = array();
$params['logging'] = true;
$params['logPath'] = '/var/logs/elasticsearch/elasticsearch.log';
$params['logPermission'] = 0664;
$client = new Elasticsearch\Client($params);

​

Not all parameters are strings. For example, we can change the logging level of the client:

$params = array();
$params['logging']  = true;
$params['logPath']  = '/var/logs/elasticsearch/elasticsearch.log';
$params['logLevel'] = Psr\Log\LogLevel::INFO;
$client = new Elasticsearch\Client($params);

​

By default, the client uses a file-based logger provided by the Monolog framework. Monolog provides a variety of loggers. For example, we can instruct the client to log to SysLog instead of a file:

use Monolog\Logger;

// Build a Monolog logger that uses the SyslogHandler
$logger    = new Logger('log');
$handler   = new SyslogHandler('my_user');
$processor = new IntrospectionProcessor();

$logger->pushHandler($handler);
$logger->pushProcessor($processor);

// Over-ride the client's logger object with your own
$params['logging']   = true;
$params['logObject'] = $logger;
$client = new Elasticsearch\Client($params);

​

The client uses the generic PSR\Log interface, which means that any PSR\Log compatible loggers will work just fine in the client.

Replacing the logger with another PSR\Log compatible logger is similar to the previous example of configuring a Monolog logger:

use Monolog\Logger;

$logger = new MySpecialPSRLogger();


$params['logging'] = true;
$params['logObject'] = $logger;
$client = new Elasticsearch\Client($params);

​

Full list of configurations

Default Configurations

$paramDefaults = array(
    'connectionClass'       => '\Elasticsearch\Connections\GuzzleConnection',
    'connectionFactoryClass'=> '\Elasticsearch\Connections\ConnectionFactory',
    'connectionPoolClass'   => '\Elasticsearch\ConnectionPool\StaticNoPingConnectionPool',
    'selectorClass'         => '\Elasticsearch\ConnectionPool\Selectors\RoundRobinSelector',
    'serializerClass'       => '\Elasticsearch\Serializers\SmartSerializer',
    'sniffOnStart'          => false,
    'connectionParams'      => array(),
    'logging'               => false,
    'logObject'             => null,
    'logPath'               => 'elasticsearch.log',
    'logLevel'              => Log\LogLevel::WARNING,
    'traceObject'           => null,
    'tracePath'             => 'elasticsearch.log',
    'traceLevel'            => Log\LogLevel::WARNING,
    'guzzleOptions'         => array(),
    'connectionPoolParams'  => array(
        'randomizeHosts' => true
    ),
    'retries'               => null
);