elasticsearch/elasticsearch - Packagist
Toggle navigation
Packagist The PHP Package Repository
Browse
Submit
Create account
Sign in
Remember me
Use Github
Log in
No account yet? Create one now!
Search by
elasticsearch / elasticsearch
PHP Client for Elasticsearch
Maintainers
Details
github.com/elastic/elasticsearch-php
Installs:
86 148 136
Dependents:
910
Suggesters:
114
Security:
Stars:
4 899
Watchers:
439
Forks:
930
v8.5.3
2022-11-22 14:15 UTC
Requires
php: ^7.4 || ^8.0elastic/transport: ^8.5guzzlehttp/guzzle: ^7.0psr/http-client: ^1.0psr/http-message: ^1.0psr/log: ^1|^2|^3
Requires (Dev)
ext-yaml: *ext-zip: *mockery/mockery: ^1.5nyholm/psr7: ^1.5php-http/mock-client: ^1.5phpstan/phpstan: ^1.4phpunit/phpunit: ^9.5symfony/finder: ~4.0symfony/http-client: ^5.0|^6.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
MIT 9d850932b8ab8129fd4baf597a1172e8f583b436
clientsearchelasticsearchelastic
dev-main
8.6.x-dev
8.5.x-dev
v8.5.3
v8.5.2
v8.5.1
v8.5.0
8.4.x-dev
v8.4.3
v8.4.2
v8.4.1
v8.4.0
8.3.x-dev
v8.3.3
v8.3.2
v8.3.1
v8.3.0
8.2.x-dev
v8.2.3
v8.2.2
v8.2.1
v8.2.0
8.1.x-dev
v8.1.0
8.0.x-dev
v8.0.1
v8.0.0
v8.0.0-rc2
v8.0.0-rc1
v8.0.0-alpha
7.x-dev
7.17.x-dev
v7.17.1
v7.17.0
7.16.x-dev
v7.16.0
7.15.x-dev
v7.15.0
7.14.x-dev
v7.14.0
7.13.x-dev
v7.13.1
v7.13.0
7.12.x-dev
v7.12.0
7.11.x-dev
v7.11.0
7.10.x-dev
v7.10.0
7.9.x-dev
v7.9.1
v7.9.0
7.8.x-dev
v7.8.0
7.7.x-dev
v7.7.0
v7.6.1
v7.6.0
v7.5.2
v7.5.1
v7.5.0
7.4.x-dev
v7.4.2
v7.4.1
v7.4.0
v7.3.0
7.2.x-dev
v7.2.2
v7.2.1
v7.2.0
v7.1.1
v7.1.0
7.0.x-dev
v7.0.2
v7.0.1
v7.0.0
6.x-dev
6.8.x-dev
v6.8.2
v6.8.1
v6.8.0
6.7.x-dev
v6.7.2
v6.7.1
v6.7.0
6.5.x-dev
v6.5.1
v6.5.0
v6.1.0
6.0.x-dev
v6.0.1
v6.0.0
v6.0.0-beta1
5.x-dev
v5.5.0
v5.4.0
v5.3.2
v5.3.1
v5.3.0
v5.2.0
v5.1.3
v5.1.2
v5.1.1
v5.1.0
5.0.x-dev
v5.0.0
2.x-dev
v2.4.0
v2.3.2
v2.3.1
v2.3.0
v2.2.3
v2.2.2
v2.2.1
v2.2.0
v2.1.5
v2.1.4
v2.1.3
v2.1.2
v2.1.1
v2.1.0
2.0.x-dev
v2.0.3
v2.0.2
v2.0.1
v2.0.0
v2.0.0-beta5
v2.0.0-beta4
v2.0.0-beta3
v2.0.0-beta2
v2.0.0-beta1
1.x-dev
v1.4.1
v1.4.0
v1.3.4
v1.3.3
v1.3.2
v1.3.1
v1.3.0
v1.2.2
v1.2.1
v1.2.0
v1.1.0
1.0.x-dev
v1.0.2
v1.0.1
v1.0
0.4.x-dev
v0.4.5
v0.4.4
v0.4.3
v0.4.2
v0.4.1
v0.4.0
dev-bump_8.5_to_8.5.4
dev-bump_main_to_8.7.0
dev-bump_main_to_8.6.0
dev-dra/assemble-with-workflow
dev-add/bump
dev-fix/1242
dev-fix/getenv
dev-toby-sutor-patch-1
dev-feature/master/dockerized-build
dev-fix/7.4.2
dev-exchange-build-status-widgets-7x
This package is auto-updated.
Last update: 2022-12-08 18:05:06 UTC
README
Elasticsearch PHP client
This is the official PHP client for
Elasticsearch.
Contents
Getting started
Configuration
Use Elastic Cloud
Usage
Index a document
Search a document
Delete a document
Versioning
Backward Incompatible Changes
Mock the Elasticsearch client
FAQ
Contribute
License
Getting started 🐣
Using this client assumes that you have an
Elasticsearch server installed and
running.
You can install the client in your PHP project using
composer:
composer require elasticsearch/elasticsearch
After the installation you can connect to Elasticsearch using the
ClientBuilder class. For instance, if your Elasticsearch is running on
localhost:9200 you can use the following code:
use Elastic\Elasticsearch\ClientBuilder;
$client = ClientBuilder::create()
->setHosts(['localhost:9200'])
->build();
// Info API
$response = $client->info();
echo $response['version']['number']; // 8.0.0
The $response is an object of Elastic\Elasticsearch\Response\Elasticsearch
class that implements ElasticsearchInterface, PSR-7
ResponseInterface
and ArrayAccess.
This means the $response is a PSR-7
object:
echo $response->getStatusCode(); // 200
echo (string) $response->getBody(); // Response body in JSON
and also an "array", meaning you can access the response body as an
associative array, as follows:
echo $response['version']['number']; // 8.0.0
var_dump($response->asArray()); // response body content as array
Moreover, you can access the response body as object, string or bool:
echo $response->version->number; // 8.0.0
var_dump($response->asObject()); // response body content as object
var_dump($response->asString()); // response body as string (JSON)
var_dump($response->asBool()); // true if HTTP response code between 200 and 300
Configuration
Elasticsearch 8.0 offers
security by default,
that means it uses TLS
for protect the communication between client and server.
In order to configure elasticsearch-php for connecting to Elasticsearch 8.0 we
need to have the certificate authority file (CA).
You can install Elasticsearch in different ways, for instance using
Docker
you need to execute the followind command:
docker pull docker.elastic.co/elasticsearch/elasticsearch:8.0.1
Once you have the docker image installed, you can execute Elasticsearch, for
instance using a single-node cluster configuration, as follows:
docker network create elastic
docker run --name es01 --net elastic -p 9200:9200 -p 9300:9300 -it docker.elastic.co/elasticsearch/elasticsearch:8.0.1
This command creates an elastic Docker network and start Elasticsearch
using the port 9200 (default).
When you run the docker imnage a password is generated for the elastic user
and it's printed to the terminal (you might need to scroll back a bit in the
terminal to view it). You have to copy it since we will need to connect to
Elasticsearch.
Now that Elasticsearch is running we can get the http_ca.crt file certificate.
We need to copy it from the docker instance, using the following command:
docker cp es01:/usr/share/elasticsearch/config/certs/http_ca.crt .
Once we have the http_ca.crt certificate and the password, copied during the
start of Elasticsearch, we can use it to connect with elasticsearch-php as
follows:
$client = ClientBuilder::create()
->setHosts(['https://localhost:9200'])
->setBasicAuthentication('elastic', 'password copied during Elasticsearch start')
->setCABundle('path/to/http_ca.crt')
->build();
For more information about the Docker configuration of Elasticsearch you can
read the official documentation
here.
Use Elastic Cloud
You can use Elastic Cloud as server with
elasticsearch-php. Elastic Cloud is the PaaS solution offered by
Elastic.
For connecting to Elastic Cloud you just need the Cloud ID and the API key.
You can get the Cloud ID from the My deployment page of your dashboard (see
the red rectangle reported in the screenshot).
You can generate an API key in the Management page under the section
Security.
When you click on Create API key button you can choose a name and set the
other options (for example, restrict privileges, expire after time, and so on).
After this step you will get the API keyin the API keys page.
IMPORTANT: you need to copy and store the API keyin a secure place, since
you will not be able to view it again in Elastic Cloud.
Once you have collected the Cloud ID and the API key, you can use
elasticsearch-php to connect to your Elastic Cloud instance, as follows:
$client = ClientBuilder::create()
->setElasticCloudId('insert here the Cloud ID')
->setApiKey('insert here the API key')
->build();
Usage
The elasticsearch-php client offers 400+ endpoints for interacting with
Elasticsearch. A list of all these endpoints is available in the
official documentation
of Elasticsearch APIs.
Here we reported the basic operation that you can perform with the client:
index, search and delete.
Index a document
You can store (index) a JSON document in Elasticsearch using the following code:
use Elastic\Elasticsearch\Exception\ClientResponseException;
use Elastic\Elasticsearch\Exception\ServerResponseException;
$params = [
'index' => 'my_index',
'body' => [ 'testField' => 'abc']
];
try {
$response = $client->index($params);
} catch (ClientResponseException $e) {
// manage the 4xx error
} catch (ServerResponseException $e) {
// manage the 5xx error
} catch (Exception $e) {
// eg. network error like NoNodeAvailableException
print_r($response->asArray()); // response body content as array
Elasticsearch stores the {"testField":"abc"} JSON document in the my_index
index. The ID of the document is created automatically by Elasticsearch and
stored in $response['_id'] field value. If you want to specify an ID for the
document you need to store it in $params['id'].
You can manage errors using ClientResponseException and
ServerResponseException. The PSR-7 response is available using
$e->getResponse() and the HTTP status code is available using $e->getCode().
Search a document
Elasticsearch provides many different way to search documents. The simplest
search that you can perform is a
match query,
as follows:
$params = [
'index' => 'my_index',
'body' => [
'query' => [
'match' => [
'testField' => 'abc'
];
$response = $client->search($params);
printf("Total docs: %d\n", $response['hits']['total']['value']);
printf("Max score : %.4f\n", $response['hits']['max_score']);
printf("Took : %d ms\n", $response['took']);
print_r($response['hits']['hits']); // documents
Using Elasticsearch you can perform different query search, for more information
we suggest toread the official documention reported
here.
Delete a document
You can delete a document specifing the index name and the ID of the
document, as follows:
use Elastic\Elasticsearch\Exception\ClientResponseException;
try {
$response = $client->delete([
'index' => 'my_index',
'id' => 'my_id'
]);
} catch (ClientResponseException $e) {
if ($e->getCode() === 404) {
// the document does not exist
if ($response['acknowledge'] === 1) {
// the document has been delete
For more information about the Elasticsearch REST API you can read the official
documentation here.
Versioning
This client is versioned and released alongside Elasticsearch server.
To guarantee compatibility, use the most recent version of this library within
the major version of the corresponding Enterprise Search implementation.
For example, for Elasticsearch 7.16, use 7.16 of this library or above, but
not 8.0.
Backward Incompatible Changes 💥
The 8.0.0 version of elasticsearch-php contains a new implementation compared
with 7.x. It supports PSR-7 for HTTP
messages and PSR-18 for HTTP client
communications.
We tried to reduce the BC breaks as much as possible with 7.x but there are
some (big) differences:
we changed the namespace, now everything is under Elastic\Elasticsearch
we used the
elastic-transport-php
library for HTTP communications;
we changed the Exception model, using the namespace
Elastic\Elasticsearch\Exception. All the exceptions extends the
ElasticsearchException interface, as in 7.x
we changed the response type of each endpoints using an
Elasticsearch response class. This class
wraps a a PSR-7 response allowing the
access of the body response as array or object. This means you can access the
API response as in 7.x, no BC break here! 👼
we changed the ConnectionPool in NodePool. The connection naming was
ambigous since the objects are nodes (hosts)
You can have a look at the BREAKING_CHANGES file for more
information.
Mock the Elasticsearch client
If you need to mock the Elasticsearch client you just need to mock a
PSR-18 HTTP Client.
For instance, you can use the
php-http/mock-client as follows:
use Elastic\Elasticsearch\ClientBuilder;
use Elastic\Elasticsearch\Response\Elasticsearch;
use Http\Mock\Client;
use Nyholm\Psr7\Response;
$mock = new Client(); // This is the mock client
$client = ClientBuilder::create()
->setHttpClient($mock)
->build();
// This is a PSR-7 response
$response = new Response(
200,
[Elasticsearch::HEADER_CHECK => Elasticsearch::PRODUCT_NAME],
'This is the body!'
);
$mock->addResponse($response);
$result = $client->info(); // Just calling an Elasticsearch endpoint
echo $result->asString(); // This is the body!
We are using the ClientBuilder::setHttpClient() to set the mock client.
You can specify the response that you want to have using the
addResponse($response) function. As you can see the $response is a PSR-7
response object. In this example we used the Nyholm\Psr7\Response object from
the nyholm/psr7 project. If you are using
PHPUnit you can even mock the ResponseInterface as
follows:
$response = $this->createMock('Psr\Http\Message\ResponseInterface');
Notice: we added a special header in the HTTP response. This is the product
check header, and it is required for guarantee that elasticsearch-php is
communicating with an Elasticsearch server 8.0+.
For more information you can read the
Mock client
section of PHP-HTTP documentation.
FAQ 🔮
Where do I report issues with the client?
If something is not working as expected, please open an
issue.
Where else can I go to get help?
You can checkout the
Elastic community discuss forums.
Contribute 🚀
We welcome contributors to the project. Before you begin, some useful info...
If you want to contribute to this project you need to subscribe to a
Contributor Agreement.
Before opening a pull request, please create an issue to
discuss the scope of your proposal.
If you want to send a PR for version 8.0 please use the 8.0 branch, for
8.1 use the 8.1 branch and so on.
Never send PR to master unless you want to contribute to the development
version of the client (master represents the next major version).
Each PR should include a unit test using PHPUnit.
If you are not familiar with PHPUnit you can have a look at the
reference.
Thanks in advance for your contribution! ❤️
License 📗
MIT Elastic
About Packagist
Atom/RSS Feeds
Statistics
Browse Packages
API
Mirrors
Status
Packagist maintenance and hosting is provided by Private Packagist