Skip to content

Commit 8864c75

Browse files
szabostevegithub-actions[bot]
szabosteve
authored and
github-actions[bot]
committed
[DOCS] Adds getting started content based on the template (#1329)
(cherry picked from commit dc469d4)
1 parent cb7b11c commit 8864c75

File tree

4 files changed

+246
-0
lines changed

4 files changed

+246
-0
lines changed

‎docs/getting-started.asciidoc

Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
[[getting-started-php]]
2+
== Getting started
3+
4+
This page guides you through the installation process of the PHP client, shows
5+
you how to instantiate the client, and how to perform basic Elasticsearch
6+
operations with it.
7+
8+
[discrete]
9+
=== Requirements
10+
11+
* TO DO
12+
* http://getcomposer.org[composer]
13+
14+
If you don't have composer you can install it by running the following commands:
15+
16+
[source,shell]
17+
--------------------------
18+
curl -s http://getcomposer.org/installer | php
19+
php composer.phar install
20+
--------------------------
21+
22+
23+
[discrete]
24+
=== Installation
25+
26+
To install the latest version of the client, run the following command:
27+
28+
[source,shell]
29+
--------------------------
30+
composer require elasticsearch/elasticsearch
31+
--------------------------
32+
33+
When you have installed elasticsearch-php you can start using it with the
34+
`Client` class. You can use the `ClientBuilder` class to create this object:
35+
36+
[source,php]
37+
--------------------------
38+
require 'vendor/autoload.php';
39+
40+
$client = Elastic\Elasticsearch\ClientBuilder::create()->build();
41+
--------------------------
42+
43+
Refer to the <<installation>> page to learn more.
44+
45+
46+
[discrete]
47+
=== Connecting
48+
49+
You can connect to the Elastic Cloud using an API key and the Elasticsearch
50+
endpoint.
51+
52+
[source,php]
53+
----
54+
$client = ClientBuilder::create()
55+
->setElasticsearchEndpoint('<elasticsearch-endpoint>')
56+
->setApiKey('<api-key>')
57+
->build();
58+
----
59+
60+
Your Elasticsearch endpoint can be found on the **My deployment** page of your
61+
deployment:
62+
63+
image::images/es_endpoint.jpg[alt="Finding Elasticsearch endpoint",align="center"]
64+
65+
You can generate an API key on the **Management** page under Security.
66+
67+
image::images/create_api_key.png[alt="Create API key",align="center"]
68+
69+
For other connection options, refer to the <<connecting>> section.
70+
71+
72+
[discrete]
73+
=== Operations
74+
75+
Time to use Elasticsearch! This section walks you through the basic, and most
76+
important, operations of Elasticsearch. For more operations and more advanced
77+
examples, refer to the <<operations>> page.
78+
79+
80+
[discrete]
81+
==== Creating an index
82+
83+
This is how you create the `my_index` index:
84+
85+
[source,php]
86+
----
87+
$client = ClientBuilder::create()->build();
88+
$params = [
89+
'index' => 'my_index'
90+
];
91+
92+
// Create the index
93+
$response = $client->indices()->create($params);
94+
----
95+
96+
97+
[discrete]
98+
==== Indexing documents
99+
100+
This is a simple way of indexing a document:
101+
102+
[source,php]
103+
----
104+
$params = [
105+
'index' => 'my_index',
106+
'body' => [ 'testField' => 'abc']
107+
];
108+
109+
// Document will be indexed to my_index/_doc/<autogenerated ID>
110+
$response = $client->index($params);
111+
----
112+
113+
You can bulk index documents with batches in a slightly more complex way:
114+
115+
.Bulk indexing with batches
116+
[source,php]
117+
----
118+
$params = ['body' => []];
119+
120+
for ($i = 1; $i <= 1234567; $i++) {
121+
$params['body'][] = [
122+
'index' => [
123+
'_index' => 'my_index',
124+
'_id' => $i
125+
]
126+
];
127+
128+
$params['body'][] = [
129+
'my_field' => 'my_value',
130+
'second_field' => 'some more values'
131+
];
132+
133+
// Every 1000 documents stop and send the bulk request
134+
if ($i % 1000 == 0) {
135+
$responses = $client->bulk($params);
136+
137+
// erase the old bulk request
138+
$params = ['body' => []];
139+
140+
// unset the bulk response when you are done to save memory
141+
unset($responses);
142+
}
143+
}
144+
145+
// Send the last batch if it exists
146+
if (!empty($params['body'])) {
147+
$responses = $client->bulk($params);
148+
}
149+
----
150+
151+
152+
[discrete]
153+
==== Getting documents
154+
155+
You can get documents by using the following code:
156+
157+
[source,php]
158+
----
159+
$params = [
160+
'index' => 'my_index',
161+
'id' => 'my_id'
162+
];
163+
164+
// Get doc at /my_index/_doc/my_id
165+
$response = $client->get($params);
166+
----
167+
168+
169+
[discrete]
170+
==== Searching documents
171+
172+
This is how you can create a single match query with the PHP client:
173+
174+
[source,php]
175+
----
176+
$params = [
177+
'index' => 'my_index',
178+
'body' => [
179+
'query' => [
180+
'match' => [
181+
'testField' => 'abc'
182+
]
183+
]
184+
]
185+
];
186+
187+
$results = $client->search($params);
188+
----
189+
190+
191+
[discrete]
192+
==== Updating documents
193+
194+
This is how you can update a document, for example to add a new field:
195+
196+
[source,php]
197+
----
198+
$params = [
199+
'index' => 'my_index',
200+
'id' => 'my_id',
201+
'body' => [
202+
'doc' => [
203+
'new_field' => 'abc'
204+
]
205+
]
206+
];
207+
208+
// Update doc at /my_index/_doc/my_id
209+
$response = $client->update($params);
210+
----
211+
212+
213+
[discrete]
214+
==== Deleting documents
215+
216+
[source,php]
217+
----
218+
$params = [
219+
'index' => 'my_index',
220+
'id' => 'my_id'
221+
];
222+
223+
// Delete doc at /my_index/_doc_/my_id
224+
$response = $client->delete($params);
225+
----
226+
227+
228+
[discrete]
229+
==== Deleting an index
230+
231+
[source,php]
232+
----
233+
$params = ['index' => 'my_index'];
234+
$response = $client->indices()->delete($params);
235+
----
236+
237+
238+
[discrete]
239+
== Further reading
240+
241+
* Use <<client-helpers>> for a more confortable experience with the APIs.

‎docs/images/es_endpoint.jpg

361 KB
Loading

‎docs/index.asciidoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
88

99
include::overview.asciidoc[]
1010

11+
include::getting-started.asciidoc[]
12+
1113
include::installation.asciidoc[]
1214

1315
include::connecting.asciidoc[]

‎docs/overview.asciidoc

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,9 @@ from one language to the next with minimal effort.
1212
The client is designed to facilitate the API call using different way to read the
1313
results using associative array, object, string or https://www.php-fig.org/psr/psr-7/[PSR-7].
1414

15+
Refer to the <<getting-started-php>> page for a step-by-step quick start with
16+
the PHP client.
17+
1518
[discrete]
1619
[[psr-7-standard]]
1720
=== PSR 7 standard

0 commit comments

Comments
 (0)