Elasticsearch 8 的新 PHP 客户端已从头开始重写。除了采用 PSR 标准外，我们还重新设计了架构并将 HTTP 传输层移到了外部。由于 HTTPlug 库，现在还可以使用可插拔系统。

继续阅读以探索：

PHP 客户端的新架构和特性
如何使用 HTTP 消息的 PSR-7标准使用端点和管理错误
如何使用异步方法与 Elasticsearch 交互

旧客户端

elasticsearch-php 库是使用 PHP 编程 Elasticsearch 的官方客户端。这个库使用一个 main 客户端类公开了 Elasticsearch 的所有 400 多个端点。在这个库的第 7 版中，所有端点都使用函数公开——例如，index API 映射到方法 Client::index()。

这些函数返回一个关联数组，该数组是来自 Elasticsearch 的 HTTP 响应的反序列化。通常，此响应由 JSON 消息表示。使用 PHP 的 json_decode() 函数将此消息转换为数组。

如果出现错误，客户端会根据问题抛出异常。例如，如果 HTTP 响应是 404，客户端会抛出 Missing404Exception。如果要检索 HTTP 响应本身，则需要使用以下代码从客户端获取最后一个响应：



1.  $response = $client->info();
2.  $last = $client->transport->getLastConnection()->getLastRequestInfo();

4.  $request = $last['request']; // associative array of the HTTP request
5.  var_dump($request);

7.  $response = $last['response']; // associative array of the HTTP response
8.  echo $response['status']; // 200
9.  echo $response['body'];   // the body as string

HTTP 请求和响应通过以下几种方法从 transport 层（客户端的属性）检索：getLastConnection() 和 getLastRequestInfo()。

这段代码不能提供良好的开发体验，因为关联数组 $response 的键非常多，来自 PHP 的 cURL 扩展的使用。

新的客户

我们从头开始构建新的 elasticsearch-php 8 有很多原因：开发人员体验、新的 PHP 标准、更开放的架构和性能。

安装了大约 7000 万次，我们不希望版本 8 有很多 BC 中断。我们使用向后兼容的方法提供与版本 7 相同的 API。这意味着你通常可以使用相同的代码连接到 Elasticsearch 并执行端点调用。不同之处在于响应。在版本 8 中，响应是 Elasticsearch 响应的对象，实现了 PSR-7 响应接口和 PHP 的 ArrayAccess 接口。

等一下 — 这不是 BC 的中断吗？幸运的是，我们实现了 ArrayAccess 接口，你可以继续以数组的形式消费响应，如下所示：

发现差异：命名空间已更改！我们引入了 Elastic 根命名空间。其他代码看起来相同，但引擎盖下有很大的变化。

正如我们所提到的，版本 8 中的 $response 是一个对象，而版本 7 中这是一个关联数组。如果你想要与版本 7 完全相同的行为，你可以使用函数$ response->asArray() 将响应序列化为数组。

我们还提供 asObject()、asString() 和 asBool() 函数将主体序列化为 PHP 标准类 (stdClass) 的对象，作为字符串或布尔值（如果 2xx 响应则为 true，否则为 false）。

例如，你可以使用之前的 info() 端点，如下所示：



1.  $client = ClientBuilder::create()
2.     ->setHosts(['localhost:9200'])
3.     ->build();
4.  $response = $client->info();

6.  echo $response['version']['number'];
7.  echo $response->version->number; // 8.0.0

9.  var_dump($response->asObject()); // response body content as stdClass object
10.  var_dump($response->asString()); // response body as string (JSON)
11.  var_dump($response->asBool());   // true if HTTP response code 2xx

$response 能够作为实现 PHP 的 _get() 魔术方法的对象访问响应主体。

如果要读取 HTTP 响应，则不需要从 Client 对象中恢复最后一条消息；你可以在 $response 本身中访问 PSR-7 消息，如下所示：



1.  echo $response->getStatusCode();    // 200, since $response is PSR-7
2.  echo (string) $response->getBody(); // Response body in JSON

这是一个很大的优势，尤其是当你使用异步时。事实上，如果你使用异步编程，则无法从客户端检索到最后的响应。不能保证最后一个响应就是你要查找的响应（本文后面将详细介绍异步操作）

自动完成的端点参数

我们使用 Psalm 项目的类对象数组在 elasticsearch-php 版本 8 中添加了自动完成功能。 Psalm 是一个静态分析工具，允许开发人员使用特殊的 phpDoc 属性来修饰代码。其中一个属性是@psalm-type，它可以指定关联数组的键类型。我们使用标准的 phpDoc @param 应用了 Psalm 类型。每个 PHP 客户端端点都有一个输入参数，即 $params 数组。例如，这里报告的是 index() 端点部分：



1.  /**
2.      * Creates or updates a document in an index.
3.      *
4.      * @see https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-index_.html
5.      *
6.      * @param array{
7.      *     id: string, //  Document ID
8.      *     index: string, // (REQUIRED) The name of the index
9.      *     wait_for_active_shards: string, // Sets the number of shard copies …
10.      *     op_type: enum, // Explicit operation type. Defaults to `index` for requests…
11.      *     refresh: enum, // If `true` then refresh the affected shards to make this operation…
12.      *     routing: string, // Specific routing value
13.      *     timeout: time, // Explicit operation timeout
14.      *     version: number, // Explicit version number for concurrency control
15.      *     version_type: enum, // Specific version type
16.      *     if_seq_no: number, // only perform the index operation if the last operation…
17.      *     if_primary_term: number, // only perform the index operation if the last operation…
18.      *     pipeline: string, // The pipeline id to preprocess incoming documents with
19.      *     require_alias: boolean, // When true, requires destination to be an alias…
20.      *     pretty: boolean, // Pretty format the returned JSON response. (DEFAULT: false)
21.      *     human: boolean, // Return human readable values for statistics. (DEFAULT: true)
22.      *     error_trace: boolean, // Include the stack trace of returned errors. (DEFAULT: false)
23.      *     source: string, // The URL-encoded request definition. Useful for libraries…
24.      *     filter_path: list, // A comma-separated list of filters used to reduce the response.
25.      *     body: array, // (REQUIRED) The document
26.      * } $params
27.      */
28.     public function index(array $params = [])

所有参数都用名称（索引）指定，包括类型（字符串）和描述参数的注释（索引的名称）。所需参数使用 REQUIRED 注释指定。

你可以使用以前的表示法在 IDE 中进行自动完成。例如，使用 PhpStorm，你可以安装 deep-assoc-completion 免费插件以启用具有 @psalm-type 属性的 PHP 关联数组自动完成。

Elasticsearch PHP client 8.x deep-assoc-completion

Elasticsearch PHP client 8.x deep-assoc-completion_哔哩哔哩_bilibili

即使此版本仍在开发中，[elastic-transport-php](marketplace.visualstudio.com/items?item>… Studio Code也可以使用 deep-assoc-completion。

可插拔架构

我们在版本 8 中所做的另一个更改是从库中拆分 HTTP 传输层。我们创建了

该库基于可插拔架构，这意味着您可以将其配置为使用以下接口的特定实现：

PSR-18 客户端，使用 ClientInterface
一个节点池，使用 NodePoolInterface
PSR-3 记录器，使用 LoggerInterface

elasticsearch-php 版本 8 使用 elastic-transport-php 作为依赖项。这意味着你可以使用自定义 HTTP 库、自定义节点池或自定义记录器连接到 Elasticsearch。

我们使用 HTTPlug 库来执行 PHP 应用程序中可用的 PSR-18 和 PSR-7 库的自动发现。默认情况下，如果应用程序没有安装 HTTP 库，我们使用 Guzzle。

例如，你可以使用Symfony HTTP 客户端，如下所示：



1.  use Symfony\Component\HttpClient\Psr18Client;

3.  $client = ClientBuilder::create()
4.     ->setHttpClient(new Psr18Client)
5.     ->build();

或者，你可以使用 Monolog 记录器库，如下所示：



1.  use Monolog\Logger;
2.  use Monolog\Handler\StreamHandler;

4.  $logger = new Logger('name');
5.  $logger->pushHandler(new StreamHandler('path/to/your.log', Logger::WARNING));
6.  $client = ClientBuilder::create()
7.     ->setLogger($logger)
8.     ->build();

有关如何自定义客户端的更多信息，请查看配置页面。

连接到 Elastic Cloud

Elastic Cloud 是 Elastic 提供的 PaaS 解决方案。要连接到 Elastic Cloud，你只需要 Cloud ID 和 API 密钥。

可以在 Elastic Cloud 仪表板的我的部署页面中检索 Cloud ID。 API 密钥可以从安全页面设置中的管理部分生成。

你可以阅读 PHP 客户端文档的连接部分以获取更多信息。

收集 Cloud ID 和 API 密钥后，你可以使用 elasticsearch-php 连接到你的 Elastic Cloud 实例，如下所示：



1.  $client = ClientBuilder::create()
2.     ->setElasticCloudId('insert here the Cloud ID')
3.     ->setApiKey('insert here the API key')
4.     ->build();

默认安全

如果你在基础架构中安装了 Elasticsearch 8，则可以使用启用了 TLS（传输层安全）的 PHP 客户端。 Elasticsearch 8 默认提供安全性，这意味着它使用 TLS 来保护客户端和服务器之间的通信。

为了配置 elasticsearch-php 以连接到 Elasticsearch 8，你需要拥有证书授权文件 (CA)。

你可以通过不同的方式安装 Elasticsearch。如果使用 Docker，则需要执行以下命令：

docker pull docker.elastic.co/elasticsearch/elasticsearch:8.1.0

安装 Docker 映像后，你可以使用单节点集群配置执行 Elasticsearch，如下所示：



1.  docker network create elastic
2.  docker run --name es01 --net elastic -p 9200:9200 -p 9300:9300 -it docker.elastic.co/elasticsearch/elasticsearch:8.1.0

此命令创建一个弹性 Docker 网络并使用端口 9200（默认）启动 Elasticsearch。

当你运行 Docker 映像时，将为 Elastic 用户生成一个密码并将其打印到终端（你可能需要在终端中向后滚动一点才能查看它）。你必须复制它才能连接到 Elasticsearch。

现在 Elasticsearch 正在运行，我们可以获得 http_ca.crt 文件证书。使用以下命令从 Docker 实例复制它：

docker cp es01:/usr/share/elasticsearch/config/certs/http_ca.crt .

一旦我们有了在 Elasticsearch 启动期间复制的 http_ca.crt 证书和密码，我们就可以使用它进行如下连接：



1.  $client = ClientBuilder::create()
2.     ->setHosts(['https://localhost:9200'])
3.     ->setBasicAuthentication('elastic', 'password copied during ES start')
4.     ->setCABundle('path/to/http_ca.crt')
5.     ->build();

在异步模式下使用客户端

PHP 客户端提供了为每个端点执行异步调用的可能性。在版本 7 中，你需要在作为端点参数传递的客户端密钥中指定一个特殊的 future => lazy，如下所示：



1.  $params = [
2.     'index' => 'my-index',
3.     'client' => [
4.        'future' => 'lazy'
5.     ],
6.     'body' => [
7.         'foo' => 'bar'
8.     ]
9.  ];
10.  $response = $client->index($params);

前面的示例使用异步 HTTP 调用在 Elasticsearch 中索引 { "foo": "bar" } 文档。 $response 是一个 future，而不是实际的响应。

future 代表 future 的计算，并且充当占位符。你可以像常规对象一样在代码周围传递 future。当你需要结果值时，你可以解决 future。如果 future 已经解决（由于某些其他活动），则这些值立即可用。如果 future 还没有被解析，解析会阻塞，直到这些值变得可用（例如，在 API 调用完成之后）。

在版本 7 中，future 实际上是 RingPHP 项目的 Promise。在版本 8 中，如果你想使用异步，你需要为您的 HTTP 客户端安装特定的适配器。例如，如果你使用 Guzzle 7（elasticsearch-php 的默认 HTTP 库），则需要安装 php-http/guzzle7-adapter，如下所示：

composer require php-http/guzzle7-adapter

要使用异步调用执行端点，你需要使用 Client::setAsync(true) 函数启用它，如下所示：



1.  $client->setAsync(true);
2.  $params = [
3.     'index' => 'my-index',
4.     'body' => [
5.         'foo' => 'bar'
6.     ]
7.  ];
8.  $response = $client->index($params);

如果要为下一个端点禁用异步，则需要再次将 setAsync 设置为 false。

异步调用的响应是 HTTPlug 库的 Promise 对象。这个 Promise 遵循 Promises/A+ 标准。 Promise 代表异步操作的最终结果。

要获得响应，你需要等待该响应到达。这将阻塞等待响应的执行，如下所示：



1.  $response = $client->index($params);
2.  $response = $response->wait();
3.  printf("Body response:\n%s\n", $response->asString());

与 Promise 交互的主要方式是通过其 then 方法，该方法注册回调以接收 Promise 的最终值或无法实现 Promise 的原因。



1.  $response = $client->index($params);
2.  $response->then(
3.     // The success callback
4.     function (ResponseInterface $response) {
5.         // $response is Elastic\Elasticsearch\Response\Elasticsearch
6.         printf("Body response:\n%s\n", $response->asString());
7.     },
8.     // The failure callback
9.     function (\Exception $exception) {
10.         echo 'Houston, we have a problem';
11.         throw $exception;
12.     }
13.  );
14.  $response = $response->wait();

需要最后一个 $response->wait() 来解决上面示例中的执行调用。

更少的代码和内存使用

新的 Elasticsearch PHP 客户端与版本 7 相比使用的代码更少。特别是，elasticsearch-php 版本 8 由 6,522 行代码 + elastic-transport-php 的 1,025 行代码组成，总共 7,547 行。在版本 7 中，我们有 20,715 行代码，因此新版本 8 的大小约为之前的三分之一。

在内存使用方面，elasticsearch-php 版本 8 实现了延迟加载机制来优化 API 命名空间加载。这意味着如果您只使用所有 400 多个端点的一个子集，你将不会在内存中加载所有规范。

总结

Elasticsearch 8 带来了一些令人兴奋的改进。从新架构和保持与版本 7 的向后兼容性的能力，到默认的安全设置和异步模式的优势，可能性从未像现在这样无穷无尽。

最好的入门方法是使用 Elastic Cloud。立即开始免费试用 Elastic Cloud！

原文：Introducing the new PHP client for Elasticsearch 8 | Elastic Blog

Elasticsearch：为 Elasticsearch 8.x 引入新的 PHP 客户端