README

从 sleimanx2/plastic 分支而来

这只是针对 v0.3.1 版本中 PlasticPaginator 的一个分支，以解决在最新版本中已解决的 PHP >= 7.0.0 的问题。

旨在在 PHP 5.6.* 中使用，并继续为旧版本的 PHP 和 Elasticsearch 添加最新版本的功能。

Plastic 是 Laravel 的 Elasticsearch ODM 和映射器。它通过提供流畅的映射、查询和存储 Eloquent 模型的语法，使开发者在使用 Elasticsearch 时体验更愉快。

此包仍在积极开发中，可能会发生变化。

对于 Elasticsearch v2，请参阅版本 < 0.4.0。

安装 Plastic

composer require lordfm/plastic=v0.3.1

如果您使用的是 Laravel >=5.5，服务提供程序将 自动发现，否则我们需要将 plastic 服务提供程序添加到 config/app.php 中的 providers 键下

LoRDFM\Plastic\PlasticServiceProvider::class

最后，我们需要运行

php artisan vendor:publish

这将创建一个位于 config/plastic.php 的配置文件和一个位于 database/mappings 的映射目录。

用法

定义可搜索模型
存储模型内容
搜索
聚合
建议
映射
填充索引
访问客户端

定义可搜索模型

要开始，请在模型中添加 LoRDFM\Plastic\Searchable 特性以启用搜索功能

use LoRDFM\Plastic\Searchable;

class Book extends Model
{
    use Searchable;
}

定义要存储的数据。

默认情况下，Plastic 将使用 $model->toArray() 存储模型的所有可见属性。

此外，Plastic 还提供了两种方式来手动指定哪些属性/关系应存储在 Elasticsearch 中。

1 - 为我们的模型提供一个可搜索属性

public $searchable = ['id', 'name', 'body', 'tags', 'images'];

2 - 提供一个 buildDocument 方法

public function buildDocument()
{
    return [
        'id' => $this->id,
        'tags' => $this->tags
    ];
}

自定义弹性类型名称

默认情况下，Plastic 将使用模型表名作为模型类型。您可以通过向模型添加 $documentType 属性来自定义它。

public $documentType = 'custom_type';

自定义弹性索引名称

默认情况下，Plastic 将使用配置文件中定义的索引。您可以通过将 $documentIndex 属性设置到模型中来自定义模型数据将存储在哪个索引中。

public $documentIndex = 'custom_index';

存储模型内容

当您从我们的 SQL DB 中保存或删除模型时，Plastic 会自动同步模型数据与弹性，但此功能可以通过在模型中添加 public $syncDocument = false 来禁用。

需要注意的是，在以下多种场景中应执行手动文档更新

1 - 当您执行批量更新或删除时，没有 Eloquent 事件被触发，因此文档数据不会同步。

2 - Plastic 目前还没有监听相关模型的事件，因此当您更新相关模型的内容时，应考虑更新父文档。

保存文档

$book = Book::first()->document()->save();

部分更新文档

$book = Book::first()->document()->update();

删除文档

$book = Book::first()->document()->delete();

批量保存文档

Plastic::persist()->bulkSave(Tag::find(1)->books);

批量删除文档

$authors = Author::where('age','>',25)->get();

Plastic::persist()->bulkDelete($authors);

搜索模型内容

Plastic 提供了一种流畅的语法来查询 Elasticsearch，这使得代码更加紧凑易读。让我们深入了解

$result = Book::search()->match('title','pulp')->get();

// Returns a collection of Book Models
$books = $result->hits();

// Returns the total number of matched documents
$result->totalHits();

// Returns the highest query score
$result->maxScore();

//Returns the time needed to execute the query
$result->took();

要获取将要执行的原始 DSL 查询，您可以调用 toDSL()

$dsl = Book::search()->match('title','pulp')->toDSL();

分页

$books = Book::search()
    ->multiMatch(['title', 'description'], 'ham on rye', ['fuzziness' => 'AUTO'])
    ->sortBy('date')
    ->paginate();

您仍然可以使用 result 方法访问分页后的结果对象

$books->result();

布尔查询

User::search()
    ->must()
        ->term('name','kimchy')
    ->mustNot()
        ->range('age',['from'=>10,'to'=>20])
    ->should()
        ->match('bio','developer')
        ->match('bio','elastic')
    ->filter()
        ->term('tag','tech')
    ->get();

嵌套查询

$contain = 'foo';

Post::search()
    ->multiMatch(['title', 'body'], $contain)
    ->nested('tags', function (SearchBuilder $builder) use ($contain) {
        $builder->match('tags.name', $contain);
    })->get();

查看 Plastic 支持的搜索查询和如何应用不支持的查询的文档。

动态更改索引

要为单个查询切换到不同的索引，只需使用 index 方法。

$result = Book::search()->index('special-books')->match('title','pulp')->get();

聚合

$result = User::search()
    ->match('bio', 'elastic')
    ->aggregate(function (AggregationBuilder $builder) {
        $builder->average('average_age', 'age');
    })->get();

$aggregations = $result->aggregations();

查看 Plastic 支持的聚合和如何应用不支持的聚合的文档。

建议

Plastic::suggest()->completion('tag_suggest', 'photo')->get();

建议查询构建器也可以直接从模型访问

//this be handy if you have a custom index for your model
Tag::suggest()->term('tag_term','admin')->get();

模型映射

映射是 Elasticsearch 的一个重要方面。您可以将它们与 SQL 数据库的索引进行比较。映射模型可以获得更好的搜索结果和更高的效率，并允许我们使用一些特殊的查询函数，如嵌套字段和建议。

生成模型映射

php artisan make:mapping "App\User"

新的映射将被放置在您的 database/mappings 目录中。

映射结构

映射类包含一个名为 map 的单个方法。map 方法用于映射给定的模型字段。

在 map 方法中，您可以使用 Plastic Map 构建器明确地创建字段映射。例如，让我们看看一个创建 Tag 模型映射的示例映射

use LoRDFM\Plastic\Map\Blueprint;
use LoRDFM\Plastic\Mappings\Mapping;

class AppTag extends Mapping
{
    /**
     * Full name of the model that should be mapped
     *
     * @var string
     */
    protected $model = App\Tag::class;

    /**
     * Run the mapping.
     *
     * @return void
     */
    public function map()
    {
        Map::create($this->getModelType(), function (Blueprint $map) {
            $map->string('name')->store('true')->index('analyzed');

            // instead of the fluent syntax we can use the second method argument to fill the attributes
            $map->completion('suggestion', ['analyzer' => 'simple', 'search_analyzer' => 'simple']);
        },$this->getModelIndex());
    }
}

要了解 Map 构建器上所有可用的方法，请查看此文档。

运行映射

可以使用 Artisan 控制台命令运行创建的映射。

php artisan mapping:run

更新映射

如果您的更新仅包括添加新的字段映射，您始终可以更新我们的模型映射，并运行。

php artisan mapping:rerun

现有字段的映射无法更新或删除，因此您需要使用以下技术之一来更新现有字段。

1 - 创建新索引

您始终可以创建新的 Elasticsearch 索引并重新运行映射。在运行映射后，您可以使用 bulkSave 方法将 SQL 数据与 Elasticsearch 同步。

2 - 使用别名

建议使用别名创建 Elasticsearch 索引，以简化更新模型映射的过程，实现零停机时间。要了解更多信息，请查看

https://elastic.ac.cn/blog/changing-mapping-with-zero-downtime

填充索引

通过运行 Artisan 控制台命令来填充索引中的可搜索模型

php artisan plastic:populate [--mappings][--index=...][--database=...]

--mappings 在填充索引之前创建模型映射
--database=... 用于映射的数据库连接，而不是默认连接
--index=... 要填充的索引，而不是默认索引

要配置从哪个模型重新创建文档的列表，必须在 config/plastic.php 中为每个索引配置一次。

    'populate' => [
        'models' => [
            // Models for the default index
            env('PLASTIC_INDEX', 'plastic') => [
                App\Models\Article::class,
                App\Models\Page::class,
            ],
            // Models for the index "another_index"
            'another_index' => [
                App\Models\User::class,
            ],
        ],
    ],

访问客户端

您可以通过以下方式访问 Elasticsearch 客户端来管理您的索引和别名

$client = Plastic::getClient();

//index delete
$client->indices()->delete(['index'=> Plastic::getDefaultIndex()]);
//index create
$client->indices()->create(['index' => Plastic::getDefaultIndex()]);

有关官方 Elastic 客户端的更多信息：https://github.com/elastic/elasticsearch-php

贡献

感谢您的贡献，贡献指南可以在这里找到。

许可证

Plastic 是开源软件，在MIT 许可证下发布。

待办事项

搜索查询构建器

实现 Boosting 查询
实现 ConstantScore 查询
实现 DisMaxQuery 查询
实现 MoreLikeThis 查询（使用原始 Eloquent 模型）
实现 GeoShape 查询

聚合查询构建器

实现 Nested 聚合
实现 ExtendedStats 聚合
实现 TopHits 聚合

映射

找到一种无缝更新字段映射且无需停机时间的方法，使用别名

通用

更好的查询构建器文档

lordfm / plastic

维护者

详细信息