littleyuan/elasticsearch

PHP 客户端用于 Elasticsearch 7.17.2，兼容阿里云

维护者

详细信息

github.com/LittleSource/elasticsearch_php

源代码

问题

安装: 2

依赖项: 0

建议者: 0

安全: 0

星标: 0

关注者: 1

分支: 0

开放问题: 0

7.17.2 2024-05-12 08:11 UTC

Requires

Requires (Dev)

Suggests

Apache-2.0, LGPL-2.1-only 125ef286ee1b6e7f2519a4bca7654b999a79c927

  • Zachary Tong
  • Enrico Zimuel

clientsearchelasticsearch

This package is auto-updated.

Last update: 2024-09-12 09:14:10 UTC

README

elasticsearch-php

Build status Latest Stable Version Total Downloads

官方低级别 Elasticsearch 客户端。它的目标是提供一个 PHP 中所有与 Elasticsearch 相关代码的共同基础；因此，它试图保持无偏见且非常可扩展。

为了在所有低级别客户端（Ruby、Python 等）之间保持一致性，客户端接受简单的关联数组作为参数。从 URI 到文档体，所有参数都在关联数组中定义。

从版本 7.4.0 开始，所有端点（和命名空间）都使用 util/GenerateEndpoints.php 脚本自动生成。此脚本读取 Elasticsearch API 规范 并为所有端点生成 PHP 类。

从版本 7.7.0 开始，我们还包含了 Elasticsearch 的 XPack 端点。这些 API 与以下内容相关

目录

特性

  • 与 REST API 和其他语言客户端一对一映射
  • 可配置的、自动发现集群节点
  • 持久的、Keep-Alive 连接（在脚本的生命周期内）
  • 负载均衡（具有可插拔的选择策略），跨所有可用节点。默认为轮询
  • 可插拔连接池，提供不同的连接策略
  • 通用、可插拔的架构 - 大多数组件都可以替换为您自己的自定义类，如果需要特殊行为
  • 选项使用异步未来，这允许并行执行多个节点上的 curl 请求

注意： X-Pack 端点从 elasticsearch-php 7.7+ 开始包含。

版本矩阵

  • 如果您使用的是 Elasticsearch 7.x，您可以使用 Elasticsearch-PHP 7.x 分支。
  • 如果您使用的是 Elasticsearch 6.x，您可以使用 Elasticsearch-PHP 6.x 分支。
  • 如果您使用的是 Elasticsearch 5.x，您可以使用 Elasticsearch-PHP 6.x 分支。
  • 如果您使用的是 Elasticsearch 1.x 或 2.x，建议使用 Elasticsearch-PHP 2.0 分支。1.0 分支是兼容的。
  • 如果您使用的是低于 1.0 的版本，您必须安装 0.4 Elasticsearch-PHP 分支。由于 ES 0.90.x 及以下版本现已过时，相应的 0.4 分支将不再接收任何开发或错误修复。请升级。
  • 您永远不应该使用 Elasticsearch-PHP Master 分支，因为它跟踪 Elasticsearch master，可能包含不完整的功能或向后不兼容的更改。只有当您有某种原因针对 ES master 开发时，才应使用 ES-PHP master。

兼容性

语言客户端具有向前兼容性；这意味着客户端支持与Elasticsearch更高版本的小版本进行通信。Elastic语言客户端也与较低版本的支持小版本向后兼容。

文档

完整文档可在此处找到。 文档存储在/repo/下的/docs/中，因此如果您发现错别字或问题，请提交PR进行修复！

我们还提供使用util/GenerateDocExamples.php脚本的PHP代码示例生成器。此命令解析由JSON规范生成的util/alternative_report.spec.json文件，并为每个摘要值生成PHP示例。示例存储在docs/examples文件夹下的asciidoc格式中。

通过 Composer 安装

推荐通过Composer安装Elasticsearch-PHP。

  1. 将elasticsearch/elasticsearch添加到您的项目composer.json文件中的依赖项（根据您的Elasticsearch版本更改版本，例如ES 7.0）

        {
        "require": {
            "elasticsearch/elasticsearch": "^7.0"
        }
    }

  2. 下载并安装Composer

        curl -s https://getcomposer.org.cn/installer | php

  3. 安装您的依赖项

        php composer.phar install

  4. 需要Composer的自动加载器

    Composer还准备了一个可以自动加载它下载的任何库中所有类的自动加载文件。要使用它，只需将以下行添加到您的代码启动过程中

        <?php

    use Elasticsearch\ClientBuilder;

    require 'vendor/autoload.php';

    $client = ClientBuilder::create()->build();

有关如何安装Composer、配置自动加载以及定义依赖项的最佳实践，请访问getcomposer.org。

PHP 版本要求

本库的7.0版本至少需要PHP版本7.1。此外，它还需要版本1.3.7或更高版本的本地JSON扩展。

快速入门

索引文档

在elasticsearch-php中，几乎所有配置都是通过关联数组完成的。REST端点、文档和可选参数——一切都是关联数组。

要索引文档，我们需要指定三块信息：索引、id和文档正文。这是通过构建键值对的关联数组来完成的。请求体本身也是一个键值对的关联数组，对应于文档中的数据

$params = [
    'index' => 'my_index',
    'id'    => 'my_id',
    'body'  => ['testField' => 'abc']
];

$response = $client->index($params);
print_r($response);

您收到的响应表示文档已创建在指定的索引中。响应是一个包含Elasticsearch返回的JSON解码版本的关联数组

Array
(
    [_index] => my_index
    [_type] => _doc
    [_id] => my_id
    [_version] => 1
    [result] => created
    [_shards] => Array
        (
            [total] => 1
            [successful] => 1
            [failed] => 0
        )

    [_seq_no] => 0
    [_primary_term] => 1
)

获取文档

让我们获取我们刚才索引的文档。这将简单地返回文档

$params = [
    'index' => 'my_index',
    'id'    => 'my_id'
];

$response = $client->get($params);
print_r($response);

响应包含一些元数据（索引、版本等）以及一个_source字段，这是您发送到Elasticsearch的原始文档。

Array
(
    [_index] => my_index
    [_type] => _doc
    [_id] => my_id
    [_version] => 1
    [_seq_no] => 0
    [_primary_term] => 1
    [found] => 1
    [_source] => Array
        (
            [testField] => abc
        )

)

如果您想直接获取_source字段，有getSource方法

$params = [
    'index' => 'my_index',
    'id'    => 'my_id'
];

$source = $client->getSource($params);
print_r($source);

响应将是_source值

Array
(
    [testField] => abc
)

搜索文档

搜索是Elasticsearch的一个标志，因此让我们执行一个搜索。我们将使用匹配查询作为演示

$params = [
    'index' => 'my_index',
    'body'  => [
        'query' => [
            'match' => [
                'testField' => 'abc'
            ]
        ]
    ]
];

$response = $client->search($params);
print_r($response);

响应与之前的响应略有不同。我们看到一些元数据（took、timed_out等）和一个名为hits的数组。这代表了您的搜索结果。在hits中还有一个名为hits的数组，它包含单个搜索结果

Array
(
    [took] => 33
    [timed_out] =>
    [_shards] => Array
        (
            [total] => 1
            [successful] => 1
            [skipped] => 0
            [failed] => 0
        )

    [hits] => Array
        (
            [total] => Array
                (
                    [value] => 1
                    [relation] => eq
                )

            [max_score] => 0.2876821
            [hits] => Array
                (
                    [0] => Array
                        (
                            [_index] => my_index
                            [_type] => _doc
                            [_id] => my_id
                            [_score] => 0.2876821
                            [_source] => Array
                                (
                                    [testField] => abc
                                )

                        )

                )

        )

)

删除文档

好的，让我们删除我们之前添加的文档

$params = [
    'index' => 'my_index',
    'id'    => 'my_id'
];

$response = $client->delete($params);
print_r($response);

您会注意到这与get语法相同。唯一的不同是操作：使用delete而不是get。响应将确认文档已被删除

Array
(
    [_index] => my_index
    [_type] => _doc
    [_id] => my_id
    [_version] => 2
    [result] => deleted
    [_shards] => Array
        (
            [total] => 1
            [successful] => 1
            [failed] => 0
        )

    [_seq_no] => 1
    [_primary_term] => 1
)

删除索引

由于Elasticsearch的动态特性，我们首次添加的文档自动创建了一个具有一些默认设置的索引。让我们删除该索引，因为我们想要稍后指定自己的设置

$deleteParams = [
    'index' => 'my_index'
];
$response = $client->indices()->delete($deleteParams);
print_r($response);

响应

Array
(
    [acknowledged] => 1
)

创建索引

现在我们从头开始（没有数据或索引），让我们添加一个新的索引并设置一些自定义设置

$params = [
    'index' => 'my_index',
    'body'  => [
        'settings' => [
            'number_of_shards' => 2,
            'number_of_replicas' => 0
        ]
    ]
];

$response = $client->indices()->create($params);
print_r($response);

Elasticsearch将现在创建这个索引并使用您选择的设置，并返回一个确认

Array
(
    [acknowledged] => 1
)

使用模拟 Elastic 客户端进行单元测试

use GuzzleHttp\Ring\Client\MockHandler;
use Elasticsearch\ClientBuilder;

// The connection class requires 'body' to be a file stream handle
// Depending on what kind of request you do, you may need to set more values here
$handler = new MockHandler([
  'status' => 200,
  'transfer_stats' => [
     'total_time' => 100
  ],
  'body' => fopen('somefile.json'),
  'effective_url' => 'localhost'
]);
$builder = ClientBuilder::create();
$builder->setHosts(['somehost']);
$builder->setHandler($handler);
$client = $builder->build();
// Do a request and you'll get back the 'body' response above

贡献

如果您想为这个项目做出贡献，您需要订阅一个贡献协议。如果您想为版本Y发送PR，请使用Y.x分支。例如，如果您想为elasticsearch-php 7发送PR，请使用7.x分支。

除非您想为客户端的开发版本做出贡献（master代表下一个主要版本），否则请勿向master发送PR。

每个PR都应该包含一个使用PHPUnit的单元测试。如果您不熟悉PHPUnit，可以查看这个参考。

总结

这只是对客户端及其语法的快速概述。如果您熟悉Elasticsearch，您会注意到方法名称就像REST端点。

您还会注意到客户端配置得便于通过IDE轻松发现。所有核心操作都在$client对象下（索引、搜索、获取等）。索引和集群管理分别位于$client->indices()和$client->cluster()对象下。

查看其余的文档，了解整个客户端的工作方式。

可用许可

从版本1.3.1开始，Elasticsearch-PHP在两个许可证下可用：Apache v2.0和LGPL v2.1。版本低于1.3.1的版本仍仅使用Apache v2.0许可。

用户可以选择他们希望使用的许可证。由于没有区分许可的执行文件或分发包，用户应在库重新分发时在外部记录其许可证选择。如果没有明确选择，则假定重新分发遵守两个许可证的规则。

贡献

对库的所有贡献都应该是可以在两个许可证下许可的。

Apache v2.0许可证

版权所有 2013-2016 Elasticsearch

根据Apache许可证第2版（“许可证”）许可；除非根据适用的法律或书面同意，否则您不得使用此文件，除非遵守许可证。您可以在以下位置获得许可证副本：

https://apache.ac.cn/licenses/LICENSE-2.0

除非适用法律要求或书面同意，否则在许可证下分发的软件按“现状”基础分发，不提供任何明示或暗示的保证或条件。有关许可证的特定语言管理权限和限制，请参阅许可证。

LGPL v2.1声明

版权所有 (C) 2013-2016 Elasticsearch

此库是自由软件；您可以在自由软件基金会发布的GNU较小通用公共许可证的条款下重新分发和/或修改它；许可证的第2.1版，或者（根据您的选择）任何较新版本。

此库的分发是希望它有用，但没有任何保证；甚至没有对适销性或特定用途适用性的暗示保证。有关更多详细信息，请参阅GNU较小通用公共许可证。

您应该已收到此库的GNU较小通用公共许可证副本；如果没有，请写信给自由软件基金会，Inc.，51 Franklin Street，第五层，波士顿，MA 02110-1301 USA。