1
1
<img align =" right " width =" auto " height =" auto " src =" https://www.elastic.co/static-res/images/elastic-logo-200.png " />
2
2
3
- Elasticsearch PHP client
4
- ========================
3
+ # Elasticsearch PHP client
5
4
6
5
[ ![ Build status] ( https://github.com/elastic/elasticsearch-php/workflows/PHP%20test/badge.svg )] ( https://github.com/elastic/elasticsearch-php/actions ) [ ![ Latest Stable Version] ( https://poser.pugx.org/elasticsearch/elasticsearch/v/stable )] ( https://packagist.org/packages/elasticsearch/elasticsearch ) [ ![ Total Downloads] ( https://poser.pugx.org/elasticsearch/elasticsearch/downloads )] ( https://packagist.org/packages/elasticsearch/elasticsearch )
7
6
8
- This is the official PHP client for
7
+ This is the official PHP client for
9
8
[ Elasticsearch] ( https://www.elastic.co/elasticsearch/ ) .
10
9
10
+ ** [ Download the latest version of Elasticsearch] ( https://www.elastic.co/downloads/elasticsearch ) **
11
+ or
12
+ ** [ sign-up] ( https://cloud.elastic.co/registration?elektra=en-ess-sign-up-page ) **
13
+ ** for a free trial of Elastic Cloud** .
14
+
11
15
## Contents
12
16
13
17
- [ Installation] ( #installation )
@@ -27,73 +31,73 @@ This is the official PHP client for
27
31
Refer to the [ Installation section] ( https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_installation )
28
32
of the getting started documentation.
29
33
30
- ## Connecting
34
+ ## Connecting
31
35
32
36
Refer to the [ Connecting section] ( https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_connecting )
33
37
of the getting started documentation.
34
38
35
39
## Usage
36
40
37
- The ` elasticsearch-php ` client offers 400+ endpoints for interacting with
38
- Elasticsearch. A list of all these endpoints is available in the
41
+ The ` elasticsearch-php ` client offers 400+ endpoints for interacting with
42
+ Elasticsearch. A list of all these endpoints is available in the
39
43
[ official documentation] ( https://www.elastic.co/guide/en/elasticsearch/reference/current/rest-apis.html )
40
44
of Elasticsearch APIs.
41
45
42
- Here we reported the basic operation that you can perform with the client:
46
+ Here we reported the basic operation that you can perform with the client:
43
47
index, search and delete.
44
48
45
- * [ Creating an index] ( https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_creating_an_index )
46
- * [ Indexing a document] ( https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_indexing_documents )
47
- * [ Getting documents] ( https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_getting_documents )
48
- * [ Searching documents] ( https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_searching_documents )
49
- * [ Updating documents] ( https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_updating_documents )
50
- * [ Deleting documents] ( https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_deleting_documents )
51
- * [ Deleting an index] ( https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_deleting_an_index )
49
+ - [ Creating an index] ( https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_creating_an_index )
50
+ - [ Indexing a document] ( https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_indexing_documents )
51
+ - [ Getting documents] ( https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_getting_documents )
52
+ - [ Searching documents] ( https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_searching_documents )
53
+ - [ Updating documents] ( https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_updating_documents )
54
+ - [ Deleting documents] ( https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_deleting_documents )
55
+ - [ Deleting an index] ( https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_deleting_an_index )
52
56
53
57
### Versioning
54
58
55
59
This client is versioned and released alongside Elasticsearch server.
56
60
57
- To guarantee compatibility, use the most recent version of this library within
61
+ To guarantee compatibility, use the most recent version of this library within
58
62
the major version of the corresponding Enterprise Search implementation.
59
63
60
- For example, for Elasticsearch ` 7.16 ` , use ` 7.16 ` of this library or above, but
64
+ For example, for Elasticsearch ` 7.16 ` , use ` 7.16 ` of this library or above, but
61
65
not ` 8.0 ` .
62
66
63
67
## Backward Incompatible Changes :boom :
64
68
65
- The 8.0.0 version of ` elasticsearch-php ` contains a new implementation compared
66
- with 7.x. It supports [ PSR-7] ( https://www.php-fig.org/psr/psr-7/ ) for HTTP
67
- messages and [ PSR-18] ( https://www.php-fig.org/psr/psr-18/ ) for HTTP client
68
- communications.
69
+ The 8.0.0 version of ` elasticsearch-php ` contains a new implementation compared
70
+ with 7.x. It supports [ PSR-7] ( https://www.php-fig.org/psr/psr-7/ ) for HTTP
71
+ messages and [ PSR-18] ( https://www.php-fig.org/psr/psr-18/ ) for HTTP client
72
+ communications.
69
73
70
- We tried to reduce the BC breaks as much as possible with ` 7.x ` but there are
74
+ We tried to reduce the BC breaks as much as possible with ` 7.x ` but there are
71
75
some (big) differences:
72
76
73
77
- we changed the namespace, now everything is under ` Elastic\Elasticsearch `
74
- - we used the
75
- [ elastic-transport-php] ( https://github.com/elastic/elastic-transport-php )
78
+ - we used the
79
+ [ elastic-transport-php] ( https://github.com/elastic/elastic-transport-php )
76
80
library for HTTP communications;
77
- - we changed the ` Exception ` model, using the namespace
78
- ` Elastic\Elasticsearch\Exception ` . All the exceptions extends the
81
+ - we changed the ` Exception ` model, using the namespace
82
+ ` Elastic\Elasticsearch\Exception ` . All the exceptions extends the
79
83
` ElasticsearchException ` interface, as in 7.x
80
- - we changed the response type of each endpoints using an
81
- [ Elasticsearch] ( src/Response/Elasticsearch.php ) response class. This class
82
- wraps a a [ PSR-7] ( https://www.php-fig.org/psr/psr-7/ ) response allowing the
83
- access of the body response as array or object. This means you can access the
84
+ - we changed the response type of each endpoints using an
85
+ [ Elasticsearch] ( src/Response/Elasticsearch.php ) response class. This class
86
+ wraps a a [ PSR-7] ( https://www.php-fig.org/psr/psr-7/ ) response allowing the
87
+ access of the body response as array or object. This means you can access the
84
88
API response as in 7.x, no BC break here! :angel :
85
- - we changed the ` ConnectionPool ` in ` NodePool ` . The ` connection ` naming was
89
+ - we changed the ` ConnectionPool ` in ` NodePool ` . The ` connection ` naming was
86
90
ambigous since the objects are nodes (hosts)
87
91
88
- You can have a look at the [ BREAKING_CHANGES] ( BREAKING_CHANGES.md ) file for more
92
+ You can have a look at the [ BREAKING_CHANGES] ( BREAKING_CHANGES.md ) file for more
89
93
information.
90
94
91
95
## Mock the Elasticsearch client
92
96
93
97
If you need to mock the Elasticsearch client you just need to mock a
94
98
[ PSR-18] ( https://www.php-fig.org/psr/psr-18/ ) HTTP Client.
95
99
96
- For instance, you can use the
100
+ For instance, you can use the
97
101
[ php-http/mock-client] ( https://github.com/php-http/mock-client ) as follows:
98
102
99
103
``` php
@@ -122,52 +126,52 @@ echo $result->asString(); // This is the body!
122
126
```
123
127
124
128
We are using the ` ClientBuilder::setHttpClient() ` to set the mock client.
125
- You can specify the response that you want to have using the
126
- ` addResponse($response) ` function. As you can see the ` $response ` is a PSR-7
127
- response object. In this example we used the ` Nyholm\Psr7\Response ` object from
128
- the [ nyholm/psr7] ( https://github.com/Nyholm/psr7 ) project. If you are using
129
- [ PHPUnit] ( https://phpunit.de/ ) you can even mock the ` ResponseInterface ` as
129
+ You can specify the response that you want to have using the
130
+ ` addResponse($response) ` function. As you can see the ` $response ` is a PSR-7
131
+ response object. In this example we used the ` Nyholm\Psr7\Response ` object from
132
+ the [ nyholm/psr7] ( https://github.com/Nyholm/psr7 ) project. If you are using
133
+ [ PHPUnit] ( https://phpunit.de/ ) you can even mock the ` ResponseInterface ` as
130
134
follows:
131
135
132
136
``` php
133
137
$response = $this->createMock('Psr\Http\Message\ResponseInterface');
134
138
```
135
139
136
- ** Notice** : we added a special header in the HTTP response. This is the product
137
- check header, and it is required for guarantee that ` elasticsearch-php ` is
140
+ ** Notice** : we added a special header in the HTTP response. This is the product
141
+ check header, and it is required for guarantee that ` elasticsearch-php ` is
138
142
communicating with an Elasticsearch server 8.0+.
139
143
140
- For more information you can read the
141
- [ Mock client] ( https://docs.php-http.org/en/latest/clients/mock-client.html )
144
+ For more information you can read the
145
+ [ Mock client] ( https://docs.php-http.org/en/latest/clients/mock-client.html )
142
146
section of PHP-HTTP documentation.
143
147
144
148
## FAQ 🔮
145
149
146
150
### Where do I report issues with the client?
147
151
148
- If something is not working as expected, please open an
152
+ If something is not working as expected, please open an
149
153
[ issue] ( https://github.com/elastic/elasticsearch-php/issues/new ) .
150
154
151
155
### Where else can I go to get help?
152
156
153
- You can checkout the
157
+ You can checkout the
154
158
[ Elastic community discuss forums] ( https://discuss.elastic.co/ ) .
155
159
156
160
## Contribute 🚀
157
161
158
162
We welcome contributors to the project. Before you begin, some useful info...
159
163
160
- + If you want to contribute to this project you need to subscribe to a
164
+ - If you want to contribute to this project you need to subscribe to a
161
165
[ Contributor Agreement] ( https://www.elastic.co/contributor-agreement ) .
162
- + Before opening a pull request, please create an issue to
166
+ - Before opening a pull request, please create an issue to
163
167
[ discuss the scope of your proposal] ( https://github.com/elastic/elasticsearch-php/issues ) .
164
- + If you want to send a PR for version ` 8.0 ` please use the ` 8.0 ` branch, for
165
- ` 8.1 ` use the ` 8.1 ` branch and so on.
166
- + Never send PR to ` master ` unless you want to contribute to the development
168
+ - If you want to send a PR for version ` 8.0 ` please use the ` 8.0 ` branch, for
169
+ ` 8.1 ` use the ` 8.1 ` branch and so on.
170
+ - Never send PR to ` master ` unless you want to contribute to the development
167
171
version of the client (` master ` represents the next major version).
168
- + Each PR should include a ** unit test** using [ PHPUnit] ( https://phpunit.de/ ) .
169
- If you are not familiar with PHPUnit you can have a look at the
170
- [ reference] ( https://phpunit.readthedocs.io/en/9.5/ ) .
172
+ - Each PR should include a ** unit test** using [ PHPUnit] ( https://phpunit.de/ ) .
173
+ If you are not familiar with PHPUnit you can have a look at the
174
+ [ reference] ( https://phpunit.readthedocs.io/en/9.5/ ) .
171
175
172
176
Thanks in advance for your contribution! :heart :
173
177
0 commit comments