Laravel 8 中文文档 Scout 全文搜索
简介
Laravel Scout 为 Eloquent 模型 的全文搜索提供了基于驱动的简单的解决方案。通过使用模型观察者， Scout 会自动同步 Eloquent 记录的搜索索引。
目前， Scout 自带一个 Algolia 驱动。不过，编写自定义驱动也很简单，你可以轻松的通过自己的搜索实现来扩展 Scout。
安装
首先，通过 Composer 包管理器来安装 Scout：
composer require laravel/scout
Scout 安装完成后，使用 vendor:publish Artisan 命令来生成 Scout 配置文件。这个命令将在你的 config 目录下生成一个 scout.php 配置文件。
php artisan vendor:publish --provider="Laravel\Scout\ScoutServiceProvider"
最后，在你要做搜索的模型中添加 Laravel\Scout\Searchable trait。这个 trait 会注册一个模型观察者来保持模型和所有驱动的同步：
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;
class Post extends Model
{
use Searchable;
}
队列
尽管 Scout 并不强制需要使用队列，但是在使用这个库之前，强烈建议你配置一个 队列驱动，使用它运行一个队列来处理允许 Scout 将模型信息同步到搜索索引的所有操作，为你的应用的 web 接口提供更快的响应。
一旦你配置了队列驱动程序，你的 config/scout.php 配置文件中 queue 选项的值要设置为 true:
'queue' => true,
驱动的先决条件
Algolia
使用 Algolia 驱动时，需要在 config/scout.php 配置文件配置你的 Algolia id 和 secret 凭证。配置好凭证之后，还需要使用 Composer 包管理器安装 Algolia PHP SDK：
composer require algolia/algoliasearch-client-php:^2.2
配置
配置模型索引
每个 Eloquent 模型都是通过给定的 「索引」 进行同步，该 「索引」 包含所有可搜索的模型记录。换句话说，你可以把每一个 「索引」 设想为一张 MySQL 数据表。默认情况下，每个模型都会被持久化到与模型的 「表」 名（通常是模型名称的复数形式）相匹配的索引。你也可以通过重写模型上的 searchableAs 方法来自定义模型的索引：
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;
class Post extends Model
{
use Searchable;
/**
* Get the index name for the model.
*
* @return string
*/
public function searchableAs()
{
return 'posts_index';
}
}
配置可搜索数据
默认情况下，模型以完整的 toArray 格式持久化到搜索索引。如果要自定义同步到搜索索引的数据，可以覆盖模型上的 toSearchableArray 方法：
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;
class Post extends Model
{
use Searchable;
/**
* 获取模型的可搜索数据。
*
* @return array
*/
public function toSearchableArray()
{
$array = $this->toArray();
// 自定义数组...
return $array;
}
}
配置模型ID
默认情况下，Scout 将使用模型的主键作为搜索索引中存储的唯一 ID 。 可以通过模型上的 getScoutKey 和 getScoutKeyName 方法自定义：
<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;
class User extends Model
{
use Searchable;
/**
* 获取模型主键。
*
* @return mixed
*/
public function getScoutKey()
{
return $this->email;
}
/**
* 获取模型键名。
*
* @return mixed
*/
public function getScoutKeyName()
{
return 'email';
}
}
识别用户
Scout 还允许您在使用 Algolia 时自动识别用户。在 Algolia 的仪表板中查看搜索分析时，将经过身份验证的用户与搜索操作相关联可能会有所帮助。您可以通过在 .env 文件中将 SCOUT_IDENTIFY 设置为 true 来启用用户标识：
SCOUT_IDENTIFY=true
启用此功能还将把请求的IP地址和经过身份验证的用户的主标识符传递给Algolia，以便此数据与用户发出的任何搜索请求相关联。
索引
批量导入
如果你想安装 Scout 到已存在的项目中，你可能已经有了想要导入搜索驱动的数据库记录。Scout 提供了 Artisan 命令 import 用来导入所有已存在的记录到搜索索引：
php artisan scout:import "App\Models\Post"
flush 命令可用于从搜索索引中删除所有模型的记录：
php artisan scout:flush "App\Models\Post"
添加记录
当你将 Laravel\Scout\Searchable trait 添加到模型中，你需要做的就是 save 一个模型实例，它将自动被添加到搜索索引。如果你已经将 Scout 配置为 使用队列，那这个操作会在后台由你的队列工作进程来执行：
$order = new App\Models\Order;
// ...
$order->save();
通过查询添加
如果你想通过 Eloquent 查询构造器将模型集合添加到搜索索引中，你也可以在 Eloquent 查询构造器上链式调用 searchable 方法。searchable 会把构造器的查询 结果分块 并且将记录添加到你的搜索索引里。同样的，如果你已经配置 Scout 为使用队列，则所有的数据块将在后台由你的队列工作进程添加：
// 通过 Eloquent 查询构造器添加...
App\Models\Order::where('price', '>', 100)->searchable();
// 你也可以通过模型关系增加记录...
$user->orders()->searchable();
// 你也可以通过集合增加记录...
$orders->searchable();
searchable 方法可以被看做是「更新插入」的操作。换句话说，如果模型记录已经在你的索引里了，它就会被更新。如果搜索索引中不存在，则将其添加到索引中。
更新记录
要更新可搜索的模型，只需要更新模型实例的属性并将模型 save 到数据库。Scout 会自动将更新同步到你的搜索索引中：
$order = App\Models\Order::find(1);
// 更新订单...
$order->save();
你也可以在 Eloquent 查询语句上使用 searchable 方法来更新一个模型的集合。如果这个模型不存在你检索的索引里，就会被创建：
// 通过 Eloquent 查询更新...
App\Models\Order::where('price', '>', 100)->searchable();
// 你也可以通过数据间的关联进行更新...
$user->orders()->searchable();
// 你也可以通过数据集合进行更新...
$orders->searchable();
删除记录
使用 delete 从数据库中删除该模型就可以移除索引里的记录。这种删除形式甚至与 软删除 的模型兼容:
$order = App\Models\Order::find(1);
$order->delete();
如果你不希望记录在删除之前被检索到，可以在 Eloquent 查询实例或集合上使用 unsearchable 方法：
// 通过 Eloquent 查询删除...
App\Models\Order::where('price', '>', 100)->unsearchable();
// 你可以通过数据间的关系进行删除...
$user->orders()->unsearchable();
// 你可以通过数据集合进行删除...
$orders->unsearchable();
暂停索引
你可能需要在执行一批 Eloquent 操作的时候，不同步模型数据到搜索索引。此时你可以使用 withoutSyncingToSearch 方法来执行此操作。这个方法接受一个立即执行的回调。该回调中所有的操作都不会同步到模型的索引：
App\Models\Order::withoutSyncingToSearch(function () {
// 执行模型操作...
});
有条件的搜索模型实例
有时候你可能需要在某些条件下模型是可搜索的。例如，假设你有 App\Models\Post 模型可能两种状态之一：「草稿」和「发布」。你可能只允许搜索 「发布」过的帖子。为了实现这一点，你需要在模型中定义一个 shouldBeSearchable 方法：
public function shouldBeSearchable()
{
return $this->isPublished();
}
只有在通过 save 方法、查询或关联模型操作时，才应使用 shouldBeSearchable 方法。直接使用 searchable 方法将使模型或集合的可搜索结果覆盖 shouldBeSearchable 方法的结果:
// 此处将遵循 "shouldBeSearchable" 结果...
App\Models\Order::where('price', '>', 100)->searchable();
$user->orders()->searchable();
$order->save();
// 此处将覆盖 "shouldBeSearchable" 结果...
$orders->searchable();
$order->searchable();
搜索
你可以使用 search 方法来搜索模型。search 方法接受一个用于搜索模型的字符串。你还需要在搜索查询上链式调用 get 方法，才能用给定的搜索语句查询与之匹配的 Eloquent 模型：
$orders = App\Models\Order::search('Star Trek')->get();
Scout 搜索返回 Eloquent 模型的集合，因此你可以直接从路由或控制器返回结果，它们会被自动转换成 JSON 格式：
use Illuminate\Http\Request;
Route::get('/search', function (Request $request) {
return App\Models\Order::search($request->search)->get();
});
如果你想在它们返回 Eloquent 模型前得到原结果，你应该使用 raw 方法：
$orders = App\Models\Order::search('Star Trek')->raw();
搜索查询通常会在模型的 searchableAs 方法指定的索引上执行。当然，你也可以使用 within 方法指定应该搜索的自定义索引：
$orders = App\Models\Order::search('Star Trek')
->within('tv_shows_popularity_desc')
->get();
Where 语句
允许你在搜索查询中增加简单的 “where” 语句。目前，这些语句只支持基本的数值等式检查，并且主要是用于根据租户 ID 进行的范围搜索查询。由于搜索索引不是关系型数据库，因此当前不支持更高级的 “where” 语句：
$orders = App\Models\Order::search('Star Trek')->where('user_id', 1)->get();
分页
除了检索模型的集合，你也可以使用 paginate 方法对搜索结果进行分页。这个方法会返回一个就像 传统的 Eloquent 查询分页 一样的 Paginator 实例：
$orders = App\Models\Order::search('Star Trek')->paginate();
你可以通过将数量作为第一个参数传递给 paginate 方法来指定每页检索多少个模型：
$orders = App\Models\Order::search('Star Trek')->paginate(15);
检索结果后，您可以显示结果并使用Blade呈现页面链接，就好像你对传统的Eloquent查询进行了分页一样：
<div class="container">
@foreach ($orders as $order)
{{ $order->price }}
@endforeach
</div>
{{ $orders->links() }}
软删除
如果你索引的模型是soft Delete，并且您需要搜索已删除的模型，请设置config / scout.php中的soft_delete选项。 配置文件为“ true”：
'soft_delete' => true,
当此配置选项为“ true”时，Scout将不会从搜索索引中删除软删除的模型。 相反，它将在索引记录上设置一个隐藏的__soft_deleted属性。 然后，您可以在搜索时使用withTrashed或onlyTrashed方法来检索软删除的记录：
// 检索结果时包括删除记录...
$orders = App\Models\Order::search('Star Trek')->withTrashed()->get();
// 检索结果时仅包括已删除记录...
$orders = App\Models\Order::search('Star Trek')->onlyTrashed()->get();
技巧：当使用“ forceDelete”软删除的模型被永久删除时，Scout会自动将其从搜索索引中删除。
自定义搜索引擎
如果您需要自定义引擎的搜索行为，则可以将回调作为第二个参数传递给search方法。 例如，您可以使用此回调将地理位置数据添加到搜索选项中，然后再将搜索查询传递给Algolia：
use Algolia\AlgoliaSearch\SearchIndex;
App\Models\Order::search('Star Trek', function (SearchIndex $algolia, string $query, array $options) {
$options['body']['query']['bool']['filter']['geo_distance'] = [
'distance' => '1000km',
'location' => ['lat' => 36, 'lon' => 111],
];
return $algolia->search($query, $options);
})->get();
自定义引擎
写引擎
如果内置的 Scout 搜索引擎不能满足你的需求，你可以编写自定义的引擎并且将它注册到 Scout。你的引擎需要继承 Laravel\Scout\Engines\Engine 抽象类，这个抽象类包含了你自定义的引擎必须要实现的八个方法：
use Laravel\Scout\Builder;
abstract public function update($models);
abstract public function delete($models);
abstract public function search(Builder $builder);
abstract public function paginate(Builder $builder, $perPage, $page);
abstract public function mapIds($results);
abstract public function map(Builder $builder, $results, $model);
abstract public function getTotalCount($results);
abstract public function flush($model);
在 Laravel\Scout\Engines\AlgoliaEngine 类里查看这些方法的实现会对你有较大的帮助。这个类会为你在学习如何在自定义引擎中实现这些方法提供一个好的起点。
注册引擎
一旦你写好了自定义引擎，你可以用 Scout 引擎管理的 extend 方法将它注册到 Scout。你只需要从 AppServiceProvider 下的 boot 方法或者应用中使用的任何一个服务提供器中调用 extend 方法。举个例子，如果你写好了一个 MySqlSearchEngine，你可以像这样去注册它：
use Laravel\Scout\EngineManager;
/**
* Bootstrap any application services.
*
* @return void
*/
public function boot()
{
resolve(EngineManager::class)->extend('mysql', function () {
return new MySqlSearchEngine;
});
}
引擎注册后，你可以在 config/scout.php 配置文件中指定它为默认的 Scout driver：
'driver' => 'mysql',
生成宏命令
如果你想要自定义生成器方法，你可以使用 Laravel\Scout\Builder 类下的 macro 方法。通常，定义「macros」时， 需要实现 service provider’s boot 方法:
<?php
namespace App\Providers;
use Illuminate\Support\Facades\Response;
use Illuminate\Support\ServiceProvider;
use Laravel\Scout\Builder;
class ScoutMacroServiceProvider extends ServiceProvider
{
/**
* 注册应用的Scout宏命令.
*
* @return void
*/
public function boot()
{
Builder::macro('count', function () {
return $this->engine->getTotalCount(
$this->engine()->search($this)
);
});
}
}
macro 函数接受一个名字作为第一个参数，第二个参数为一个闭包函数。当调用 Laravel\Scout\Builder 宏命令时，调用这个函数.
App\Models\Order::search('Star Trek')->count();