From 0b30cc058ec9c6e6704ae465a3430cf0ff1a880b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Fri, 24 Nov 2023 14:07:23 +0100 Subject: [PATCH] [DOCS] Adds a signpost for downloading ES or signing-up for ESS. (#1379) --- README.md | 106 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 55 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index c50cf5dae..7ea3e7e6b 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,17 @@ -Elasticsearch PHP client -======================== +# Elasticsearch PHP client [![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) -This is the official PHP client for +This is the official PHP client for [Elasticsearch](https://www.elastic.co/elasticsearch/). +**[Download the latest version of Elasticsearch](https://www.elastic.co/downloads/elasticsearch)** +or +**[sign-up](https://cloud.elastic.co/registration?elektra=en-ess-sign-up-page)** +**for a free trial of Elastic Cloud**. + ## Contents - [Installation](#installation) @@ -27,65 +31,65 @@ This is the official PHP client for Refer to the [Installation section](https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_installation) of the getting started documentation. -## Connecting +## Connecting Refer to the [Connecting section](https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_connecting) 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 +The `elasticsearch-php` client offers 400+ endpoints for interacting with +Elasticsearch. A list of all these endpoints is available in the [official documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/rest-apis.html) of Elasticsearch APIs. -Here we reported the basic operation that you can perform with the client: +Here we reported the basic operation that you can perform with the client: index, search and delete. -* [Creating an index](https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_creating_an_index) -* [Indexing a document](https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_indexing_documents) -* [Getting documents](https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_getting_documents) -* [Searching documents](https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_searching_documents) -* [Updating documents](https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_updating_documents) -* [Deleting documents](https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_deleting_documents) -* [Deleting an index](https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_deleting_an_index) +- [Creating an index](https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_creating_an_index) +- [Indexing a document](https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_indexing_documents) +- [Getting documents](https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_getting_documents) +- [Searching documents](https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_searching_documents) +- [Updating documents](https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_updating_documents) +- [Deleting documents](https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_deleting_documents) +- [Deleting an index](https://www.elastic.co/guide/en/elasticsearch/client/php-api/current/getting-started-php.html#_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 +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 +For example, for Elasticsearch `7.16`, use `7.16` of this library or above, but not `8.0`. ## Backward Incompatible Changes :boom: -The 8.0.0 version of `elasticsearch-php` contains a new implementation compared -with 7.x. It supports [PSR-7](https://www.php-fig.org/psr/psr-7/) for HTTP -messages and [PSR-18](https://www.php-fig.org/psr/psr-18/) for HTTP client -communications. +The 8.0.0 version of `elasticsearch-php` contains a new implementation compared +with 7.x. It supports [PSR-7](https://www.php-fig.org/psr/psr-7/) for HTTP +messages and [PSR-18](https://www.php-fig.org/psr/psr-18/) for HTTP client +communications. -We tried to reduce the BC breaks as much as possible with `7.x` but there are +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](https://github.com/elastic/elastic-transport-php) +- we used the + [elastic-transport-php](https://github.com/elastic/elastic-transport-php) library for HTTP communications; -- we changed the `Exception` model, using the namespace - `Elastic\Elasticsearch\Exception`. All the exceptions extends the +- 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](src/Response/Elasticsearch.php) response class. This class - wraps a a [PSR-7](https://www.php-fig.org/psr/psr-7/) response allowing the - access of the body response as array or object. This means you can access the +- we changed the response type of each endpoints using an + [Elasticsearch](src/Response/Elasticsearch.php) response class. This class + wraps a a [PSR-7](https://www.php-fig.org/psr/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! :angel: -- we changed the `ConnectionPool` in `NodePool`. The `connection` naming was +- 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](BREAKING_CHANGES.md) file for more +You can have a look at the [BREAKING_CHANGES](BREAKING_CHANGES.md) file for more information. ## Mock the Elasticsearch client @@ -93,7 +97,7 @@ information. If you need to mock the Elasticsearch client you just need to mock a [PSR-18](https://www.php-fig.org/psr/psr-18/) HTTP Client. -For instance, you can use the +For instance, you can use the [php-http/mock-client](https://github.com/php-http/mock-client) as follows: ```php @@ -122,52 +126,52 @@ 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](https://github.com/Nyholm/psr7) project. If you are using -[PHPUnit](https://phpunit.de/) you can even mock the `ResponseInterface` as +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](https://github.com/Nyholm/psr7) project. If you are using +[PHPUnit](https://phpunit.de/) you can even mock the `ResponseInterface` as follows: ```php $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 +**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](https://docs.php-http.org/en/latest/clients/mock-client.html) +For more information you can read the +[Mock client](https://docs.php-http.org/en/latest/clients/mock-client.html) section of PHP-HTTP documentation. ## FAQ 🔮 ### Where do I report issues with the client? -If something is not working as expected, please open an +If something is not working as expected, please open an [issue](https://github.com/elastic/elasticsearch-php/issues/new). ### Where else can I go to get help? -You can checkout the +You can checkout the [Elastic community discuss forums](https://discuss.elastic.co/). ## 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 +- If you want to contribute to this project you need to subscribe to a [Contributor Agreement](https://www.elastic.co/contributor-agreement). -+ Before opening a pull request, please create an issue to +- Before opening a pull request, please create an issue to [discuss the scope of your proposal](https://github.com/elastic/elasticsearch-php/issues). -+ 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 +- 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](https://phpunit.de/). - If you are not familiar with PHPUnit you can have a look at the - [reference](https://phpunit.readthedocs.io/en/9.5/). +- Each PR should include a **unit test** using [PHPUnit](https://phpunit.de/). + If you are not familiar with PHPUnit you can have a look at the + [reference](https://phpunit.readthedocs.io/en/9.5/). Thanks in advance for your contribution! :heart: