README

概述
安装
快速入门
贡献
开发
许可

概述

本项目提供索引助手以帮助您在不中断服务的情况下管理ES索引。此助手实现了在官方文档中描述的哲学，可以用几个词来概括：使用别名而不是直接使用索引。

版本控制

本项目使用以下版本规则

X.Y.Z

其中

X 是本项目支持的ElasticSearch主版本
Y 是此助手的版本号。请注意此规则，您可能会在两个 Y 号之间遇到一些重大变更。
Z 是此索引助手的次版本号。当有修复错误时，它将增加。

支持的版本

安装

安装此库的推荐方法是使用Composer。

在您的 composer.json 文件中添加以下依赖项

{
  "require": {
    "nexucis/es-index-helper": "X.Y.*"
  }
}

其中X.Y是符合您需求的版本。

之后，您需要安装此新依赖项

php composer.phar install

或者，您可以直接使用composer命令修改您的 composer.json 并更新您的依赖项
php composer.phar require nexucis/es-index-helper

要初始化索引助手，首先需要实例化elasticsearch客户端

<?php

use Elasticsearch\ClientBuilder;
use Nexucis\Elasticsearch\Helper\Nodowntime\IndexHelper;

require 'vendor/autoload.php';

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

要配置elasticsearch客户端，您可以阅读相关文档

快速入门

我们鼓励用户查看接口，以了解所有可用方法。以下描述并不详尽，因此如果您不查看代码，可能会错过某些方法

索引操作

创建索引

一切从创建索引开始

<?php
$alias = "myindex";
$helper->createIndexByAlias($alias);

正如您所看到的，我们通过助手传递别名名称而不是索引名称。通过助手，您将看到一切都是通过别名而不是直接通过索引来查看的。

以下方法将创建一个名为myindex的索引，并带有后缀_v1，并添加一个名为myindex的别名。

如果您直接请求ElasticSearch（例如使用Sense），您可能会看到如下内容

GET _cat/aliases
# which can give the following result : 
alias   index      filter routing.index routing.search
myIndex myindex_v1 -      -            -

删除索引

正如我们所说的，通过此助手，您将看到一切通过别名。因此，如果您想删除索引，只需传递别名，如下所示

<?php
$alias= 'myindex';
$helper->deleteIndexByAlias($alias);

如果您执行上述HTTP请求，您将看到没有任何东西剩下。别名和索引都已删除。

映射操作

此助手在您想动态更改映射并仍然希望完全访问您的数据时证明了自己的存在。

因此，为了使这一切成为可能，我们需要

创建一个名为myindex_v2的第二个索引
从myindex_v1复制设置到myindex_v2
在myindex_v2中放置新的映射
从myindex_v1复制所有文档到myIndex_v2。
删除旧索引myindex_v1并将别名myindex放在新索引中

检查更新是否成功需要很多步骤和验证。这就是为什么这个助手提供了以下简化方法。

<?php
$alias = "myindex";
$mappings = [
    'properties' => [
        'first_name' => [
            'type' => 'text',
            'analyzer' => 'standard'
        ],
        'age' => [
            'type' => 'integer'
        ]
    ]
];
$helper->updateMappings($alias, $mappings, false, true, true, false);

您只需提供别名名称和新映射，就完成了。

⚠️ 对于包含大量文档的索引，更新可能需要很长时间。因此，最好是

使用ElasticSearch 2.4，以异步方式调用此方法。
使用ElasticSearch 5或更高版本，将参数$waitForCompletion设置为false。它将返回taskID，然后可以使用_task api

⚠️ Elasticsearch已经开始在映射中移除文档类型。根据建议，方法updateMappings有一个新的参数$includeTypeName，它允许支持旧的映射格式

默认情况下，方法updateMappings将考虑旧的映射格式，例如

<?php
$alias = "myindex";
$mappings = [
    'my_type' => [
        'properties' => [
            'first_name' => [
                'type' => 'text',
                'analyzer' => 'standard'
            ],
            'age' => [
                'type' => 'integer'
            ]
        ]
    ]
];
$helper->updateMappings($alias, $mappings);

如果您想转换到新格式，必须从映射中删除类型，并将参数$includeTypeName设置为false

请注意，参数$includeTypeName将在下一个主要版本中删除

设置操作

可以使用updateSettings方法以与映射相同的方式更新索引设置。

<?php
$alias = "myindex";
$settings =[ 
    'number_of_shards' => 1,
    'number_of_replicas' => 0,
    'analysis' => [ 
        'filter' => [
            'shingle' => [
                'type' => 'shingle'
            ]
        ],
        'char_filter' => [
            'pre_negs' => [
                'type' => 'pattern_replace',
                'pattern' => '(\\w+)\\s+((?i:never|no|nothing|nowhere|noone|none|not|havent|hasnt|hadnt|cant|couldnt|shouldnt|wont|wouldnt|dont|doesnt|didnt|isnt|arent|aint))\\b',
                'replacement' => '~$1 $2'
            ],
            'post_negs' => [
                'type' => 'pattern_replace',
                'pattern' => '\\b((?i:never|no|nothing|nowhere|noone|none|not|havent|hasnt|hadnt|cant|couldnt|shouldnt|wont|wouldnt|dont|doesnt|didnt|isnt|arent|aint))\\s+(\\w+)',
                'replacement' => '$1 ~$2'
            ]
        ],
        'analyzer' => [
            'reuters' => [
                'type' => 'custom',
                'tokenizer' => 'standard',
                'filter' => ['lowercase', 'stop', 'kstem']
            ]
        ]
    ]
];
$helper->updateSettings($alias, $settings);

文档操作

此助手也提供了一些文档操作。例如，您可以添加一个文档并检索它。

<?php
$alias= "myindex";
$type = 'test';
$id='randomId';

$body = [
    'latinField' => 'Palatii dicto sciens venit contumaciter'
];

if($helper->addDocument($alias, $type, $body)){
    $document = $helper->getDocument($alias, $type, $id);
    
    // do something with this document
}

贡献

任何贡献或建议都将非常感激。请随意使用问题部分或发送拉取请求。

开发

所有以下工具都由circleci运行，因此为了帮助您改进代码并使生活更容易，以下是如何使用正确的参数启动工具。

运行单元测试

如果您想运行单元测试，您需要有一个本地Elasticsearch实例，它必须可以通过https://:9200访问。启动它的简单方法是启动相应的容器。

docker run -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" docker.elastic.co/elasticsearch/elasticsearch:7.1.1

ElasticSearch启动后，您可以运行以下命令

composer test

运行PHP_CodeSniffer

此工具将检查代码是否遵守某些编码规则。在此项目中，我们目前仅遵守PSR-2编码规则。

要运行它，请运行以下命令

composer lint src && composer lint tests

如果您对这个工具感兴趣，可以在这里了解更多信息

运行PHPStan分析器

此工具可以在不运行代码的情况下找到代码中的某些错误。