elasticsearch / elasticsearch
PHP Client for Elasticsearch
Installs: 140 635 624
Dependents: 1 034
Suggesters: 134
Security: 0
Stars: 41
Watchers: 179
Forks: 970
Open Issues: 24
Requires
- php: ^7.4 || ^8.0
- elastic/transport: ^8.10
- guzzlehttp/guzzle: ^7.0
- psr/http-client: ^1.0
- psr/http-message: ^1.1 || ^2.0
- psr/log: ^1|^2|^3
Requires (Dev)
- ext-yaml: *
- ext-zip: *
- mockery/mockery: ^1.5
- nyholm/psr7: ^1.5
- php-http/message-factory: ^1.0
- php-http/mock-client: ^1.5
- phpstan/phpstan: ^1.4
- phpunit/phpunit: ^9.5
- psr/http-factory: ^1.0
- symfony/finder: ~4.0
- symfony/http-client: ^5.0|^6.0|^7.0
- dev-main
- 8.x-dev
- 8.17.x-dev
- 8.16.x-dev
- v8.16.0
- 8.15.x-dev
- v8.15.0
- 8.14.x-dev
- v8.14.0
- 8.13.x-dev
- v8.13.0
- 8.12.x-dev
- v8.12.0
- 8.11.x-dev
- v8.11.0
- 8.10.x-dev
- v8.10.0
- 8.9.x-dev
- v8.9.0
- 8.8.x-dev
- v8.8.2
- v8.8.1
- v8.8.0
- 8.7.x-dev
- v8.7.1
- v8.7.0
- 8.6.x-dev
- v8.6.2
- v8.6.1
- v8.6.0
- 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.2
- 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.3
- 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-renovate/configure
- dev-add-catalog-info
- dev-annieh/add_cluster_code_examples_to_docs
- dev-new-yaml-tests
- dev-bump_8.10_to_8.10.1
- dev-bump_main_to_8.11.0
- dev-bump_main_to_8.8.0
- 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: 2024-11-20 12:06:36 UTC
README
Elasticsearch PHP client
This is the official PHP client for Elasticsearch.
Download the latest version of Elasticsearch or sign-up for a free trial of Elastic Cloud.
Contents
- Installation
- Connecting
- Usage
- Versioning
- Backward Incompatible Changes
- Mock the Elasticsearch client
- FAQ
- Contribute
- License
Installation
Refer to the Installation section of the getting started documentation.
Connecting
Refer to the Connecting section of the getting started documentation.
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.
- Creating an index
- Indexing a document
- Getting documents
- Searching documents
- Updating documents
- Deleting documents
- Deleting an index
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
.
Compatibility
The Elasticsearch client is compatible with currently maintained PHP versions.
Language clients are forward compatible; meaning that clients support communicating with greater or equal minor versions of Elasticsearch without breaking. It does not mean that the client automatically supports new features of newer Elasticsearch versions; it is only possible after a release of a new client version. For example, a 8.12 client version won't automatically support the new features of the 8.13 version of Elasticsearch, the 8.13 client version is required for that. Elasticsearch language clients are only backwards compatible with default distributions and without guarantees made.
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 namespaceElastic\Elasticsearch\Exception
. All the exceptions extends theElasticsearchException
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
inNodePool
. Theconnection
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 the8.0
branch, for8.1
use the8.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! ❤️