README

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

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

有关 Elasticsearch v2，请参阅版本 < 0.4.0。

安装 Plastic

composer require sleimanx2/plastic

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

Sleimanx2\Plastic\PlasticServiceProvider::class

最后，我们需要运行

php artisan vendor:publish

这将创建一个配置文件在 config/plastic.php 并一个映射目录在 database/mappings。

使用方法

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

定义可搜索模型

要开始，请通过添加 Sleimanx2\Plastic\Searchable 特性来启用模型中的搜索功能

use Sleimanx2\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 数据库保存或删除模型时，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::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 构建器明确地创建字段映射。例如，让我们看看创建一个标签模型映射的示例。

use Sleimanx2\Plastic\Map\Blueprint;
use Sleimanx2\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 聚合

映射

找到一种无缝方式，通过别名在零停机时间更新字段映射

通用

更好的查询构建器文档

rauny-henrique / plastic

维护者

详细信息