Skip to content

Commit

Permalink
[DOCS] Edits README. (#1219)
Browse files Browse the repository at this point in the history
  • Loading branch information
@szabosteve
szabosteve committed Apr 29, 2022
1 parent bcba690 commit 6fe87e1
Showing 1 changed file with 117 additions and 80 deletions.
197 changes: 117 additions & 80 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@ 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 [Elasticsearch](https://www.elastic.co/elasticsearch/).
This is the official PHP client for
[Elasticsearch](https://www.elastic.co/elasticsearch/).

## Contents

Expand All @@ -27,18 +28,20 @@ This is the official PHP client for [Elasticsearch](https://www.elastic.co/elast

## Getting started 🐣

Using this client assumes that you have an [Elasticsearch](https://www.elastic.co/elasticsearch/)
server installed and running.
Using this client assumes that you have an
[Elasticsearch](https://www.elastic.co/elasticsearch/) server installed and
running.

You can install the client in your PHP project using [composer](https://getcomposer.org/):
You can install the client in your PHP project using
[composer](https://getcomposer.org/):

```bash
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:
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:

```php

Expand All @@ -55,7 +58,8 @@ echo $response['version']['number']; // 8.0.0
```

The `$response` is an object of `Elastic\Elasticsearch\Response\Elasticsearch`
class that implements `ElasticsearchInterface`, PSR-7 [ResponseInterface](https://www.php-fig.org/psr/psr-7/#33-psrhttpmessageresponseinterface)
class that implements `ElasticsearchInterface`, PSR-7
[ResponseInterface](https://www.php-fig.org/psr/psr-7/#33-psrhttpmessageresponseinterface)
and [ArrayAccess](https://www.php.net/manual/en/class.arrayaccess.php).

This means the `$response` is a [PSR-7](https://www.php-fig.org/psr/psr-7/)
Expand Down Expand Up @@ -88,21 +92,23 @@ var_dump($response->asBool()); // true if HTTP response code between 200 and 3

## Configuration

Elasticsearch 8.0 offers [security by default](https://www.elastic.co/blog/introducing-simplified-elastic-stack-security),
Elasticsearch 8.0 offers
[security by default](https://www.elastic.co/blog/introducing-simplified-elastic-stack-security),
that means it uses [TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security)
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](https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html)
You can install Elasticsearch in different ways, for instance using
[Docker](https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html)
you need to execute the followind command:

```bash
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:
Once you have the docker image installed, you can execute Elasticsearch, for
instance using a single-node cluster configuration, as follows:

```bash
docker network create elastic
Expand All @@ -113,8 +119,9 @@ 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.
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:
Expand All @@ -124,8 +131,8 @@ 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:
start of Elasticsearch, we can use it to connect with `elasticsearch-php` as
follows:

```php
$client = ClientBuilder::create()
Expand All @@ -136,38 +143,41 @@ $client = ClientBuilder::create()
```

For more information about the Docker configuration of Elasticsearch you can
read the official documentation [here](https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html).
read the official documentation
[here](https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html).

### Use Elastic Cloud

You can use [Elastic Cloud](https://www.elastic.co/cloud/) as server with `elasticsearch-php`.
Elastic Cloud is the PaaS solution offered by [Elastic](https://www.elastic.co).
You can use [Elastic Cloud](https://www.elastic.co/cloud/) as server with
`elasticsearch-php`. Elastic Cloud is the PaaS solution offered by
[Elastic](https://www.elastic.co).

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 get the `Cloud ID` from the `My deployment` page of your dashboard (see
the red rectangle reported in the screenshot).

![Cloud ID](docs/images/cloud_id.png)

You can generate an `API key` in the `Management` page under the section `Security`.
You can generate an `API key` in the `Management` page under the section
`Security`.

![Security](docs/images/create_api_key.png)

When you click on `Create API key` button you can choose a name and set the other
options (eg. restrict privileges, expire after time, etc).
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).

![Choose an API name](docs/images/api_key_name.png)

After this step you will get the `API key`in the API keys page.

![API key](docs/images/cloud_api_key.png)

**IMPORTANT**: you need to copy and store the `API key`in a secure place, since you will not
be able to view it again in Elastic Cloud.
**IMPORTANT**: you need to copy and store the `API key`in 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:
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:

```php
$client = ClientBuilder::create()
Expand All @@ -178,11 +188,13 @@ $client = ClientBuilder::create()

## Usage

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)
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: index, search and delete.
Here we reported the basic operation that you can perform with the client:
index, search and delete.

### Index a document

Expand All @@ -209,19 +221,21 @@ try {

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()`.
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](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-match-query.html),
Elasticsearch provides many different way to search documents. The simplest
search that you can perform is a
[match query](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-match-query.html),
as follows:

```php
Expand All @@ -244,13 +258,14 @@ 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 to
read the official documention reported [here](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-your-data.html).
Using Elasticsearch you can perform different query search, for more information
we suggest toread the official documention reported
[here](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-your-data.html).

### Delete a document

You can delete a document specifing the `index` name and the `ID` of the document,
as follows:
You can delete a document specifing the `index` name and the `ID` of the
document, as follows:

```php
use Elastic\Elasticsearch\Exception\ClientResponseException;
Expand All @@ -270,43 +285,54 @@ if ($response['acknowledge'] === 1) {
}
```

For more information about the Elasticsearch REST API you can read the official documentation
[here](https://www.elastic.co/guide/en/elasticsearch/reference/current/rest-apis.html).
For more information about the Elasticsearch REST API you can read the official
documentation [here](https://www.elastic.co/guide/en/elasticsearch/reference/current/rest-apis.html).

### Versioning

This client is versioned and released alongside Elasticsearch server.
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.
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`.
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 some (big) differences:
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) library for HTTP communications;
- we changed the `Exception` model, using the namespace `Elastic\Elasticsearch\Exception`. All the exceptions extends the
- 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
`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 API response as in 7.x, no BC break here! :angel:
- we changed the `ConnectionPool` in `NodePool`. The `connection` naming was ambigous since the objects are nodes (hosts)
- 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
ambigous since the objects are nodes (hosts)

You can have a look at the [BREAKING_CHANGES](BREAKING_CHANGES.md) file for more information.
You can have a look at the [BREAKING_CHANGES](BREAKING_CHANGES.md) file for more
information.

## Mock the Elasticsearch client

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 [php-http/mock-client](https://github.com/php-http/mock-client)
as follows:
For instance, you can use the
[php-http/mock-client](https://github.com/php-http/mock-client) as follows:

```php
use Elastic\Elasticsearch\ClientBuilder;
Expand All @@ -332,43 +358,54 @@ $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](https://github.com/Nyholm/psr7)
project. If you are using [PHPUnit](https://phpunit.de/) you can even mock the
`ResponseInterface` as follows:
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 communicating
with an Elasticsearch server 8.0+.
**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 [issue](https://github.com/elastic/elasticsearh-php/issues/new).
If something is not working as expected, please open an
[issue](https://github.com/elastic/elasticsearh-php/issues/new).

### Where else can I go to get help?

You can checkout the [Elastic community discuss forums](https://discuss.elastic.co/).
You can checkout the
[Elastic community discuss forums](https://discuss.elastic.co/).

## Contribute 🚀

We welcome contributors to the project. Before you begin, a couple notes...

+ 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 [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 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/).
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](https://www.elastic.co/contributor-agreement).
+ 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
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/).

Thanks in advance for your contribution! :heart:

Expand Down

0 comments on commit 6fe87e1

Please sign in to comment.