README

在 Laravel 或 Lumen 应用程序中使用官方 Elastic Search 客户端的简单方法。

Laravel-Elasticsearch

安装和配置

通过 composer 安装 mailerlite/laravel-elasticsearch 包的当前版本

composer require mailerlite/laravel-elasticsearch

如果您正在使用 ElasticSearch 版本 5，则安装此包的版本 2

composer require mailerlite/laravel-elasticsearch:^2

Laravel

包的服务提供程序将自动注册其服务提供程序。

发布配置文件

php artisan vendor:publish --provider="MailerLite\LaravelElasticsearch\ServiceProvider"

通过 .env 文件进行替代配置方法

按照上述建议发布配置文件后，您可以通过向应用程序的 .env 文件（带有适当的值）添加以下内容来配置 ElasticSearch：

ELASTICSEARCH_HOST=localhost
ELASTICSEARCH_PORT=9200
ELASTICSEARCH_SCHEME=http
ELASTICSEARCH_USER=
ELASTICSEARCH_PASS=

如果您通过 API 密钥登录，则需要填写这些值

ELASTICSEARCH_API_ID=
ELASTICSEARCH_API_KEY=

连接到 AWS Elasticsearch 服务

如果您正在连接到 Amazon AWS 上的 ElasticSearch 实例，则还需要 composer require aws/aws-sdk-php:^3.80 并将以下内容添加到您的 .env 文件中

AWS_ELASTICSEARCH_ENABLED=true
AWS_REGION=...
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...

如果您必须使用具有自定义凭据的另一种身份验证方法（例如 instanceProfile()），则必须发布配置文件并使用 aws_credentials

<?php
// config/elasticsearch.php

$provider = \Aws\Credentials\CredentialProvider::instanceProfile();
$memoizedProvider = \Aws\Credentials\CredentialProvider::memoize($provider);
$credentials = $memoizedProvider()->wait();

...

'hosts' => [
    [
        'host'            => env('ELASTICSEARCH_HOST', 'localhost'),
        // For local development, the default Elasticsearch port is 9200.
        // If you are connecting to an Elasticsearch instance on AWS, you probably want to set this to null
        'port'            => env('ELASTICSEARCH_PORT', 9200),
        'scheme'          => env('ELASTICSEARCH_SCHEME', null),
        'user'            => env('ELASTICSEARCH_USER', null),
        'pass'            => env('ELASTICSEARCH_PASS', null),

        // If you are connecting to an Elasticsearch instance on AWS, you will need these values as well
        'aws'             => env('AWS_ELASTICSEARCH_ENABLED', false),
        'aws_region'      => env('AWS_REGION', ''),
        'aws_key'         => env('AWS_ACCESS_KEY_ID', ''),
        'aws_secret'      => env('AWS_SECRET_ACCESS_KEY', '')
        'aws_credentials' => $credentials
    ],
],

如果您有一个在守护进程运行的作业，则必须使用 Closure。这样，凭据将在运行时更新。

<?php
// config/elasticsearch.php

$provider = \Aws\Credentials\CredentialProvider::instanceProfile();
$memoizedProvider = \Aws\Credentials\CredentialProvider::memoize($provider);

...

'hosts' => [
    [
        ...
        'aws_credentials' => $memoizedProvider
    ],
],

如果您使用 php artisan config:cache，则不能在配置文件中使用 Closure，像这样调用它

<?php
// config/elasticsearch.php

...

'hosts' => [
    [
        ...
        'aws_credentials' => [\Aws\Credentials\CredentialProvider::class, 'defaultProvider'],
    ],
],

Lumen

如果您使用 Lumen，请将服务提供程序和配置注册到 bootstrap/app.php 文件中

$app->register(MailerLite\LaravelElasticsearch\ServiceProvider::class);
$app->configure('elasticsearch');

手动将配置文件复制到您的应用程序。

使用方法

Elasticsearch 门面只是进入 ES 客户端的入口点，因此您之前可能使用过

use Elasticsearch\ClientBuilder;

$data = [
    'body' => [
        'testField' => 'abc'
    ],
    'index' => 'my_index',
    'type' => 'my_type',
    'id' => 'my_id',
];

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

现在，您可以简单地替换这两行

use Elasticsearch;

$return = Elasticsearch::index($data);

这将运行默认连接上的命令。您可以在任何连接上运行命令（请参阅配置文件中的 defaultConnection 设置和 connections 数组）。

$return = Elasticsearch::connection('connectionName')->index($data);

希望使用 Facades 的 Lumen 用户可以通过编辑 bootstrap/app.php 文件来包含以下内容

$app->withFacades(true, [
    ...
    MailerLite\LaravelElasticsearch\Facade::class => 'Elasticsearch',
    ...
]);

不使用 Facades 的 Lumen 用户需要使用依赖注入或应用程序容器来获取 ES 服务对象

// using injection:
public function handle(\Mailerlite\LaravelElasticsearch\Manager $elasticsearch)
{
    $elasticsearch->ping();
}

// using application container:
$elasticSearch = $this->app('elasticsearch');

当然，依赖注入和应用程序容器也适用于 Laravel 应用程序。

高级使用

由于此包是围绕官方 Elastic 客户端包装的，因此您可以使用此包执行几乎所有操作。您不仅可以执行标准的 CRUD 操作，还可以通过程序监控您的 Elastic 集群的健康状况，备份它或对其进行更改。这些操作中的一些是通过“命名空间”命令完成的，此包支持这些命令。

获取索引的统计信息

$stats = Elasticsearch::indices()->stats(['index' => 'my_index']);
$stats = Elasticsearch::nodes()->stats();
$stats = Elasticsearch::cluster()->stats();

创建和恢复快照（首先阅读 Elastic 文档中的创建存储库路径和插件部分）

$response = Elasticsearch::snapshots()->create($params);
$response = Elasticsearch::snapshots()->restore($params);

删除整个索引（小心！）

$response = Elasticsearch::indices()->delete(['index' => 'my_index']);

请记住，这个包是一个围绕大量非常复杂且文档齐全的Elastic功能的薄包装。有关这些功能的以及调用它们所使用的方法和参数的信息，可以在Elastic文档中找到。有关如何使用这些功能的帮助可以在Elastic论坛和类似Stack Overflow的网站上获得。

控制台命令

此包还提供了一些有用的控制台命令。

检查索引是否存在

php artisan laravel-elasticsearch:utils:index-exists <your_elasticsearch_index_name>

创建索引

php artisan laravel-elasticsearch:utils:index-create <your_elasticsearch_index_name>

删除索引

php artisan laravel-elasticsearch:utils:index-delete <your_elasticsearch_index_name>

创建或更新索引映射： 注意：索引映射文件必须包含Elasticsearch期望的有效JSON映射定义，例如：

{
    "body": {
        "_source": {
            "enabled": true
        },
        "properties": {
            "id": {
                "type": "keyword"
            },
            "property_1": {
                "type": "text"
            },
            "property_2": {
                "type": "text"
            }
        }
    }
}

php artisan laravel-elasticsearch:utils:index-create-or-update-mapping <your_elasticsearch_index_name> <json_mapping_absolute_file_path>

创建别名

php artisan laravel-elasticsearch:utils:alias-create <your_elasticsearch_index_name> <your_elasticsearch_alias_name>

从别名中移除索引

php artisan laravel-elasticsearch:utils:alias-remove-index <your_elasticsearch_index_name> <your_elasticsearch_alias_name>

切换别名上的索引（对于新索引的无缝发布非常有用）

php artisan laravel-elasticsearch:utils:alias-switch-index <your_NEW_elasticsearch_index_name> <your_OLD_elasticsearch_index_name> <your_elasticsearch_alias_name>

错误、建议、贡献和支持

感谢所有为这个项目做出贡献的人！

请使用Github来报告错误、发表评论或建议。

有关如何贡献更改，请参阅CONTRIBUTING.md。

版权和许可

laravel-elasticsearch是感谢Colin Viebrock编写的，并在MIT许可证下发布。它由MailerLite维护和开发。

版权（c）2023 MailerLite

mailerlite / laravel-elasticsearch

维护者

详细信息