README

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

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

安装 Plastic

composer require sleimanx2/plastic

然后我们需要将 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';

存储模型内容

当您从我们的 SQL 数据库保存或删除模型时，Plastic 会自动同步模型数据与 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();

嵌套查询

$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构建器表达性地创建字段映射。例如，让我们看看一个创建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

访问客户端

您可以通过以下方式访问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聚合

映射

• 找到使用别名在零停机时间内无缝更新字段映射的方法

通用

• 更好的查询构建器文档