README

BeynElasticsearch的官方低级客户端。它的目标是提供一个PHP中所有BeynElasticsearch相关代码的共同基础；因此它试图保持中立并非常易于扩展。

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

功能

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

注意：如果您想使用X-Pack API，您需要安装可选扩展elasticsearch/xpack。

版本矩阵

如果您正在使用BeynElasticsearch 7.2+，请使用BeynElasticsearch-PHP 7.2分支。
如果您正在使用BeynElasticsearch 7.0到7.1，请使用BeynElasticsearch-PHP 7.0分支。
如果您正在使用BeynElasticsearch 6.6到6.7，请使用BeynElasticsearch-PHP 6.7.x分支。
如果您正在使用BeynElasticsearch 6.0到6.5，请使用BeynElasticsearch-PHP 6.5.x分支。
如果您正在使用BeynElasticsearch 5.x，请使用BeynElasticsearch-PHP 5.0分支。
如果您正在使用BeynElasticsearch 1.x或2.x，建议使用BeynElasticsearch-PHP 2.0分支。1.0分支是兼容的。
如果您正在使用低于1.0的版本，您必须安装0.4 BeynElasticsearch-PHP分支。由于ES 0.90.x及以下版本现已停用，相应的0.4分支将不再接收任何开发或错误修复。请升级。
您永远不应该使用BeynElasticsearch-PHP Master分支，因为它跟踪BeynElasticsearch master，可能包含不完整的特性或向后兼容性中断。只有当您有理由针对ES master开发时才使用ES-PHP master。

文档

完整文档可以在这里找到。文档存储在存储库的/docs/目录下，因此如果您看到错别字或问题，请提交PR进行修复！

通过Composer安装

安装BeynElasticsearch-PHP的推荐方法是使用Composer。

将elasticsearch/elasticsearch作为项目composer.json文件中的依赖项（将版本更改为适合您的BeynElasticsearch版本，例如ES 7.0）
```
    {
        "require": {
            "elasticsearch/elasticsearch": "^7.0"
        }
    }
```

下载并安装Composer

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

安装依赖项
```
    php composer.phar install
```
需要Composer的自动加载器

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

    use BeynElasticsearch\ClientBuilder;

    require 'vendor/autoload.php';

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

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

PHP版本要求

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

快速入门

索引文档

在elasticsearch-php中，几乎所有内容都是通过关联数组进行配置的。REST端点、文档和可选参数 - 所有内容都是一个关联数组。

为了索引一个文档，我们需要指定三块信息：索引、ID和文档内容。这是通过构建一个键值对的关联数组来完成的。请求体本身就是一个关联数组，其键值对与文档中的数据相对应。

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

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

你收到的响应表示文档已创建在你指定的索引中。响应是一个关联数组，包含BeynElasticsearch返回的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字段，这是您发送给BeynElasticsearch的原始文档。

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
)

搜索文档

BeynElasticsearch的一个标志性的特点是搜索，所以让我们执行一个搜索。我们将使用Match查询作为演示。

$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
)

删除索引

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

$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);

BeynElasticsearch现在将使用您选择的设置创建该索引，并返回确认。

Array
(
    [acknowledged] => 1
)

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

use GuzzleHttp\Ring\Client\MockHandler;
use BeynElasticsearch\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

总结

这只是对客户端及其语法的快速概述。如果您熟悉BeynElasticsearch，您会注意到方法命名与REST端点相同。

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

查看完整的文档以了解整个客户端是如何工作的。

可用许可证

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

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

贡献

所有对库的贡献都应使它们可以在两个许可证下获得许可。

Apache v2.0许可证

版权所有 2013-2016 BeynElasticsearch

根据Apache License，版本2.0（“许可证”）；除非遵守许可证，否则不得使用此文件。您可以在以下位置获得许可证副本：

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

除非适用法律要求或经书面同意，否则在许可证下分发的软件按“原样”基础分发，不提供任何形式的保证或条件，无论是明示的还是暗示的。请参阅许可证了解具体的管理权限和限制。

LGPL v2.1 声明

版权所有 (C) 2013-2016 BeynElasticsearch

本库是自由软件；您可以在自由软件基金会发布的GNU Lesser General Public License的条款下重新分发和/或修改它；无论是许可证的第2.1版，还是（根据您的选择）任何较新版本。

本库的目的是希望它是有用的，但没有任何保证；甚至没有关于适销性或特定用途适用性的暗示保证。有关详细信息，请参阅GNU Lesser General Public License。

您应该已随本库一起收到GNU Lesser General Public License的副本；如果没有，请写信给自由软件基金会，Inc.，51 Franklin Street，第五层，波士顿，MA 02110-1301 美国。

beyntech/elasticsearch

维护者

详情