README

Plastic是Laravel的Elasticsearch ODM和映射器。它通过提供映射、查询和存储eloquent模型的高效语法，使得使用Elasticsearch的开发体验更加愉快。

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

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

安装Plastic

composer require yogarine/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
    ];
}

自定义Elastic类型名称

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

public $documentType = 'custom_type';

自定义Elastic索引名称

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

public $documentIndex = 'custom_index';

存储模型内容

Plastic在您从我们的SQL数据库中保存或删除模型时自动同步模型数据与Elastic，但此功能可以通过向模型添加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();

Bool查询

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

Nested查询

$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 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许可证许可。

待办事项

搜索查询构建器

实现提升查询
实现常量得分查询
实现DisMaxQuery查询
实现MoreLikeThis查询（使用原始Eloquent模型）
实现GeoShape查询

聚合查询构建器

实现嵌套聚合
实现扩展统计聚合
实现TopHits聚合

映射

找到一种无缝更新字段映射并在别名下实现零停机时间的方法

通用

更好的查询构建器文档

优加林 / 塑料

维护者

详细信息