Skip to content

Commit dbd0699

Browse files
ezimuelezimuel
committed
Rebase docs from v8.17.0
1 parent 5b6fe18 commit dbd0699

27 files changed

+3401
-0
lines changed

‎docs/breaking-changes.asciidoc

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
[[breaking_changes]]
2+
=== Breaking changes from 7.x
3+
4+
This major release is a complete new PHP client for {es}. We build it from scratch!
5+
We tried to reduce the BC breaks as much as possible but there are some (big) differences:
6+
7+
[discrete]
8+
==== Architectural changes
9+
10+
- we changed the namespace, now everything is under `Elastic\Elasticsearch`
11+
- we used the https://github.com/elastic/elastic-transport-php[elastic-transport-php] library for HTTP communications;
12+
- we changed the `Exception` model, using the namespace `Elastic\Elasticsearch\Exception`. All the exceptions extends the
13+
`ElasticsearchException` interface, as in 7.x
14+
- we changed the response type of each endpoint using an https://github.com/elastic/elasticsearch-php/blob/master/src/Response/Elasticsearch.php[Elasticsearch] response class.
15+
This class wraps a https://www.php-fig.org/psr/psr-7/[PSR-7] response allowing the access of the body response
16+
as array or object. This means you can access the API response as in 7.x, no BC break here! :angel:
17+
- we changed the `ConnectionPool` in `NodePool`. The `connection` naming was ambigous since the objects are nodes (hosts)
18+
19+
[discrete]
20+
==== Specific changes
21+
22+
The following functions has been removed:
23+
24+
- `ClientBuilder::getEndpoint()`
25+
- `ClientBuilder::getRegisteredNamespacesBuilders()`
26+
- `ClientBuilder::getRegisteredNamespacesBuilders()`
27+
- `ClientBuilder::defaultHandler()`
28+
- `ClientBuilder::multiHandler()`
29+
- `ClientBuilder::singleHandler()`
30+
- `ClientBuilder::setConnectionFactory()`
31+
- `ClientBuilder::setConnectionPool()`, you can use `ClientBuilder::setNodePool` instead
32+
- `ClientBuilder::setEndpoint()`
33+
- `ClientBuilder::registerNamespace()`
34+
- `ClientBuilder::setTransport()`, you can specify an HTTP PSR-18 client using `ClientBuilder::setHttpClient()`
35+
- `ClientBuilder::setHandler()`
36+
- `ClientBuilder::setTracer()`, you can only set a Logger using `ClientBuilder::setLogger()`
37+
- `ClientBuilder::setSerializer()`
38+
- `ClientBuilder::setConnectionParams()`, you can use `ClientBuilder::setHttpClientOptions()` instead
39+
- `ClientBuilder::setSelector()`, you can set a `Selector` using the `setNodePool`, see https://github.com/elastic/elastic-transport-php/blob/8.x/README.md#use-a-custom-selector[here] for more information
40+
- `ClientBuilder::setSniffOnStart()`
41+
- `ClientBuilder::includePortInHostHeader()`
42+
43+
We removed the special `client` parameter passed in `$params` endpoints. In details:
44+
45+
- `$params['client']['never_retry']`
46+
- `$params['client']['verbose']`
47+
- `$params['client']['port_in_header']`
48+
- `$params['client']['future']`, you can set HTTP async using `Client::setAsync(true)`
49+
- `$params['client']['ignore']`, you can disable the Exception using `Client::setResponseException(false)`

‎docs/config-hash.asciidoc

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
[discrete]
2+
[[config-hash]]
3+
=== Building the client from a configuration hash
4+
5+
To help ease automated building of the client, all configurations can be
6+
provided in a setting hash instead of calling the individual methods directly.
7+
This functionality is exposed through the `ClientBuilder::fromConfig()` static
8+
method, which accepts an array of configurations and returns a fully built
9+
client.
10+
11+
Array keys correspond to the method name, for example `retries` key corresponds
12+
to `setRetries()` method.
13+
14+
[source,php]
15+
----
16+
$params = [
17+
'hosts' => [
18+
'localhost:9200'
19+
],
20+
'retries' => 2
21+
];
22+
$client = ClientBuilder::fromConfig($params);
23+
----
24+
25+
Unknown parameters throw an exception, to help the user find potential problems.
26+
If this behavior is not desired (for example, you are using the hash for other
27+
purposes), you can set `$quiet = true` in fromConfig() to silence the exceptions.
28+
29+
[source,php]
30+
----
31+
$params = [
32+
'hosts' => [
33+
'localhost:9200'
34+
],
35+
'retries' => 2,
36+
'imNotReal' => 5
37+
];
38+
39+
// Set $quiet to true to ignore the unknown `imNotReal` key
40+
$client = ClientBuilder::fromConfig($params, true);
41+
----

‎docs/configuration.asciidoc

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
[[configuration]]
2+
== Configuration
3+
4+
Almost every aspect of the client is configurable. Most users only need to
5+
configure a few parameters to suit their needs, but it is possible to completely
6+
replace much of the internals if required.
7+
8+
Custom configuration is accomplished before the client is instantiated, through
9+
the `ClientBuilder` class. You can find all the configuration options and
10+
check sample code that helps you replace the various components.
11+
12+
To learn more about JSON in PHP, read <<php_json_objects>>.
13+
14+
* <<host-config>>
15+
* <<set-retries>>
16+
* <<http-meta-data>>
17+
* <<enabling_logger>>
18+
* <<http-client>>
19+
* <<namespaces>>
20+
* <<node_pool>>
21+
* <<config-hash>>
22+
23+
include::php_json_objects.asciidoc[]
24+
25+
include::host-config.asciidoc[]
26+
27+
include::set-retries.asciidoc[]
28+
29+
include::http-meta-data.asciidoc[]
30+
31+
include::logger.asciidoc[]
32+
33+
include::http-client.asciidoc[]
34+
35+
include::namespaces.asciidoc[]
36+
37+
include::node-pool.asciidoc[]
38+
39+
include::config-hash.asciidoc[]

‎docs/connecting.asciidoc

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
[[connecting]]
2+
== Connecting
3+
4+
This page contains the information you need to connect and use the Client with
5+
{es}.
6+
7+
**On this page**
8+
9+
* <<auth-ec, Elastic Cloud>>
10+
* <<auth-http, Security by default (HTTPS)>>
11+
12+
[discrete]
13+
[[auth-ec]]
14+
=== Elastic Cloud
15+
16+
You can connect to https://www.elastic.co/cloud/[Elastic Cloud] using an **API key**
17+
and a **Cloud ID**:
18+
19+
[source,php]
20+
----
21+
$client = ClientBuilder::create()
22+
->setElasticCloudId('<cloud-id>')
23+
->setApiKey('<api-key>')
24+
->build();
25+
----
26+
27+
Where <cloud-id> and <api-key> can be retrieved using the Elastic Cloud web UI.
28+
29+
You can get the `Cloud ID` from the `My deployment` page of your dashboard (see the red
30+
rectangle reported in the screenshot).
31+
32+
image::images/cloud_id.png[alt="Elastic Cloud ID",align="center"]
33+
34+
You can generate an `API key` in the `Management` page under the section `Security`.
35+
36+
image::images/create_api_key.png[alt="Create API key",align="center"]
37+
38+
When you click on `Create API key` button you can choose a name and set the other
39+
options (eg. restrict privileges, expire after time, etc).
40+
41+
image::images/api_key_name.png[alt="Choose an API name",align="center"]
42+
43+
After this step you will get the `API key`in the API keys page.
44+
45+
image::images/cloud_api_key.png[alt="Cloud API key",align="center"]
46+
47+
**IMPORTANT**: you need to copy and store the `API key`in a secure place, since you will not
48+
be able to view it again in Elastic Cloud.
49+
50+
51+
[discrete]
52+
[[auth-http]]
53+
=== Security by default (HTTPS)
54+
55+
{es} 8.0 offers https://www.elastic.co/blog/introducing-simplified-elastic-stack-security[security by default],
56+
that means it uses https://en.wikipedia.org/wiki/Transport_Layer_Security[TLS]
57+
for protect the communication between client and server.
58+
59+
In order to configure `elasticsearch-php` for connecting to {es} 8.0 we
60+
need to have the certificate authority file (CA).
61+
62+
You can install {es} in different ways, for instance using https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html[Docker]
63+
you need to execute the followind command:
64+
65+
[source,shell]
66+
--------------------------
67+
docker pull docker.elastic.co/elasticsearch/elasticsearch:8.0.1
68+
--------------------------
69+
70+
Once you have the docker image installed you can execute {es},
71+
for instance using a single-node cluster configuration, as follows:
72+
73+
[source,shell]
74+
--------------------------
75+
docker network create elastic
76+
docker run --name es01 --net elastic -p 9200:9200 -p 9300:9300 -it docker.elastic.co/elasticsearch/elasticsearch:8.0.1
77+
--------------------------
78+
79+
This command creates an `elastic` Docker network and start {es}
80+
using the port `9200` (default).
81+
82+
When you run the docker image a password is generated for the `elastic` user
83+
and it's printed to the terminal (you might need to scroll back a bit in the terminal
84+
to view it). You have to copy it since we will need to connect to {es}.
85+
86+
Now that {es} is running we can get the `http_ca.crt` file certificate.
87+
We need to copy it from the docker instance, using the following command:
88+
89+
[source,shell]
90+
--------------------------
91+
docker cp es01:/usr/share/elasticsearch/config/certs/http_ca.crt .
92+
--------------------------
93+
94+
Once we have the `http_ca.crt` certificate and the `password`, copied during the
95+
start of {es} , we can use it to connect with `elasticsearch-php`
96+
as follows:
97+
98+
[source,php]
99+
--------------------------
100+
$client = ClientBuilder::create()
101+
->setHosts(['https://localhost:9200'])
102+
->setBasicAuthentication('elastic', 'password copied during Elasticsearch start')
103+
->setCABundle('path/to/http_ca.crt')
104+
->build();
105+
--------------------------
106+
107+
For more information about the Docker configuration of Elasticsearch you can
108+
read the official documentation https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html[here].
109+

0 commit comments

Comments
 (0)