1[[host-config]]
2=== Host Configuration
3
4The client offers two options to configure hosts:
5
6* <<inline-host-config>>
7* <<extended-host-config>>
8
9
10[discrete]
11[[inline-host-config]]
12==== Inline Host Configuration
13
14The most common configuration is telling the client about your cluster: the
15number of nodes, their addresses, and ports. If no hosts are specified, the
16client attempts to connect to `localhost:9200`.
17
18This behavior can be changed by using the `setHosts()` method on
19`ClientBuilder`. The method accepts an array of values, each entry corresponding
20to one node in your cluster. The format of the host can vary, depending on your
21needs (ip vs hostname, port, ssl, etc).
22
23[source,php]
24----
25$hosts = [
26    '192.168.1.1:9200',         // IP + Port
27    '192.168.1.2',              // Just IP
28    'mydomain.server.com:9201', // Domain + Port
29    'mydomain2.server.com',     // Just Domain
30    'https://localhost',        // SSL to localhost
31    'https://192.168.1.3:9200'  // SSL to IP + Port
32];
33$client = ClientBuilder::create()           // Instantiate a new ClientBuilder
34                    ->setHosts($hosts)      // Set the hosts
35                    ->build();              // Build the client object
36----
37
38Notice that the `ClientBuilder` object allows chaining method calls for brevity.
39It is also possible to call the methods individually:
40
41[source,php]
42----
43$hosts = [
44    '192.168.1.1:9200',         // IP + Port
45    '192.168.1.2',              // Just IP
46    'mydomain.server.com:9201', // Domain + Port
47    'mydomain2.server.com',     // Just Domain
48    'https://localhost',        // SSL to localhost
49    'https://192.168.1.3:9200'  // SSL to IP + Port
50];
51$clientBuilder = ClientBuilder::create();   // Instantiate a new ClientBuilder
52$clientBuilder->setHosts($hosts);           // Set the hosts
53$client = $clientBuilder->build();          // Build the client object
54----
55
56
57[discrete]
58[[extended-host-config]]
59==== Extended Host Configuration
60
61The client also supports an _extended_ host configuration syntax. The inline
62configuration method relies on PHP's `filter_var()` and `parse_url()` methods to
63validate and extract the components of a URL. Unfortunately, these built-in
64methods run into problems with certain edge-cases. For example, `filter_var()`
65will not accept URL's that have underscores (which are questionably legal,
66depending on how you interpret the RFCs). Similarly, `parse_url()` will choke if
67a Basic Auth's password contains special characters such as a pound sign (`#`)
68or question-marks (`?`).
69
70For this reason, the client supports an extended host syntax which provides
71greater control over host initialization. None of the components are validated,
72so edge-cases like underscores domain names will not cause problems.
73
74The extended syntax is an array of parameters for each host. The structure of
75the parameter list is identical to the return values of a
76http://php.net/manual/en/function.parse-url.php#refsect1-function.parse-url-returnvalues[`parse_url()`] call:
77
78[source,php]
79----
80$hosts = [
81    // This is effectively equal to: "https://username:password!#$?*abc@foo.com:9200/elastic"
82    [
83        'host' => 'foo.com',
84        'port' => '9200',
85        'scheme' => 'https',
86        'path' => '/elastic',
87        'user' => 'username',
88        'pass' => 'password!#$?*abc'
89    ],
90
91    // This is equal to "http://localhost:9200/"
92    [
93        'host' => 'localhost',    // Only host is required
94    ]
95];
96$client = ClientBuilder::create()           // Instantiate a new ClientBuilder
97                    ->setHosts($hosts)      // Set the hosts
98                    ->build();              // Build the client object
99----
100
101Only the `host` parameter is required for each configured host. If not provided,
102the default port is `9200`. The default scheme is `http`.