1[[quickstart]]
2== Quickstart
3
4This section will give you a quick overview of the client and how the major functions work.
5
6=== Installation
7
8* Include elasticsearch-php in your `composer.json` file:
9+
10[source,json]
11----------------------------
12{
13    "require": {
14        "elasticsearch/elasticsearch": "~7.0"
15    }
16}
17----------------------------
18
19* Install the client with composer:
20+
21[source,shell]
22----------------------------
23curl -s http://getcomposer.org/installer | php
24php composer.phar install --no-dev
25----------------------------
26
27* Include the autoloader in your main project (if you haven't already), and instantiate a new client :
28+
29[source,php]
30----------------------------
31require 'vendor/autoload.php';
32
33use Elasticsearch\ClientBuilder;
34
35$client = ClientBuilder::create()->build();
36----------------------------
37
38
39=== Index a document
40
41In elasticsearch-php, almost everything is configured by associative arrays.  The REST endpoint, document and optional parameters - everything is an associative array.
42
43To index a document, we need to specify three pieces of information: index, id and a document body. This is done by
44constructing an associative array of key:value pairs.  The request body is itself an associative array with key:value pairs
45corresponding to the data in your document:
46
47[source,php]
48----------------------------
49$params = [
50    'index' => 'my_index',
51    'id'    => 'my_id',
52    'body'  => ['testField' => 'abc']
53];
54
55$response = $client->index($params);
56print_r($response);
57----------------------------
58
59The response that you get back indicates the document was created in the index that you specified.  The response is an
60associative array containing a decoded version of the JSON that Elasticsearch returns:
61
62[source,php]
63----------------------------
64Array
65(
66    [_index] => my_index
67    [_type] => _doc
68    [_id] => my_id
69    [_version] => 1
70    [created] => 1
71)
72
73----------------------------
74
75=== Get a document
76
77Let's get the document that we just indexed.  This will simply return the document:
78
79[source,php]
80----------------------------
81$params = [
82    'index' => 'my_index',
83    'id'    => 'my_id'
84];
85
86$response = $client->get($params);
87print_r($response);
88----------------------------
89
90The response contains some metadata (index, version, etc.) as well as a `_source` field, which is the original document
91that you sent to Elasticsearch.
92
93[source,php]
94----------------------------
95Array
96(
97    [_index] => my_index
98    [_type] => _doc
99    [_id] => my_id
100    [_version] => 1
101    [found] => 1
102    [_source] => Array
103        (
104            [testField] => abc
105        )
106
107)
108----------------------------
109
110=== Search for a document
111
112Searching is a hallmark of elasticsearch, so let's perform a search.  We are going to use the Match query as a demonstration:
113
114[source,php]
115----------------------------
116$params = [
117    'index' => 'my_index',
118    'body'  => [
119        'query' => [
120            'match' => [
121                'testField' => 'abc'
122            ]
123        ]
124    ]
125];
126
127$response = $client->search($params);
128print_r($response);
129----------------------------
130
131The response is a little different from the previous responses.  We see some metadata (`took`, `timed_out`, etc) and
132an array named `hits`.  This represents your search results.  Inside of `hits` is another array named `hits`, which contains
133individual search results:
134
135[source,php]
136----------------------------
137Array
138(
139    [took] => 1
140    [timed_out] =>
141    [_shards] => Array
142        (
143            [total] => 5
144            [successful] => 5
145            [failed] => 0
146        )
147
148    [hits] => Array
149        (
150            [total] => 1
151            [max_score] => 0.30685282
152            [hits] => Array
153                (
154                    [0] => Array
155                        (
156                            [_index] => my_index
157                            [_type] => _doc
158                            [_id] => my_id
159                            [_score] => 0.30685282
160                            [_source] => Array
161                                (
162                                    [testField] => abc
163                                )
164                        )
165                )
166        )
167)
168----------------------------
169
170=== Delete a document
171
172Alright, let's go ahead and delete the document that we added previously:
173
174[source,php]
175----------------------------
176$params = [
177    'index' => 'my_index',
178    'id'    => 'my_id'
179];
180
181$response = $client->delete($params);
182print_r($response);
183----------------------------
184
185You'll notice this is identical syntax to the `get` syntax.  The only difference is the operation: `delete` instead of
186`get`.  The response will confirm the document was deleted:
187
188[source,php]
189----------------------------
190Array
191(
192    [found] => 1
193    [_index] => my_index
194    [_type] => _doc
195    [_id] => my_id
196    [_version] => 2
197)
198----------------------------
199
200
201=== Delete an index
202
203Due to the dynamic nature of elasticsearch, the first document we added automatically built an index with some default settings.  Let's delete that index because we want to specify our own settings later:
204
205[source,php]
206----------------------------
207$deleteParams = [
208    'index' => 'my_index'
209];
210$response = $client->indices()->delete($deleteParams);
211print_r($response);
212----------------------------
213
214The response:
215
216
217[source,php]
218----------------------------
219Array
220(
221    [acknowledged] => 1
222)
223----------------------------
224
225=== Create an index
226
227Now that we are starting fresh (no data or index), let's add a new index with some custom settings:
228
229[source,php]
230----------------------------
231$params = [
232    'index' => 'my_index',
233    'body' => [
234        'settings' => [
235            'number_of_shards' => 2,
236            'number_of_replicas' => 0
237        ]
238    ]
239];
240
241$response = $client->indices()->create($params);
242print_r($response);
243----------------------------
244
245Elasticsearch will now create that index with your chosen settings, and return an acknowledgement:
246
247[source,php]
248----------------------------
249Array
250(
251    [acknowledged] => 1
252)
253----------------------------
254
255=== Wrap up
256
257That was just a crash-course overview of the client and it's syntax.  If you are familiar with elasticsearch, you'll
258notice that the methods are named just like REST endpoints.
259
260You'll also notice that the client is configured in a manner that facilitates easy discovery via your IDE.  All core
261actions are available under the `$client` object (indexing, searching, getting, etc).  Index and cluster management
262are located under the `$client->indices()` and `$client->cluster()` objects, respectively.
263
264Check out the rest of the Documentation to see how the entire client works.
265