* * * * *
[TOC]
## 简介
Laravel Scout 为 [Eloquent 模型](https://www.kancloud.cn/tonyyu/laravel_5_6/786272) 全文搜索提供了简单的，基于驱动的解决方案。通过使用模型观察者，Scout 会自动同步 Eloquent 记录的搜索索引。
目前，Scout 自带一个 [Algolia](https://www.algolia.com/) 驱动；不过，编写自定义驱动很简单， 你可以轻松的通过自己的搜索实现来扩展 Scout。
## 安装
首先，通过 Composer 包管理器来安装 Scout：
~~~
composer require laravel/scout
~~~
Scout 安装完成之后，你应该使用 `vendor:publish` Artisan 命令来生成 Scout 配置文件。这个命令将生成 `scout.php` 配置文件到你的 `config` 目录：
~~~
php artisan vendor:publish --provider="Laravel\Scout\ScoutServiceProvider"
~~~
最后，在你想要做搜索的模型中添加 `Laravel\Scout\Searchable` trait。这个 trait 会注册一个模型观察者来保持模型和搜索驱动的同步：
~~~
<?php
namespace App;
use Laravel\Scout\Searchable;
use Illuminate\Database\Eloquent\Model;
class Post extends Model
{
use Searchable;
}
~~~
### 队列
虽然不是强制要求使用 Scout，但在使用这个库之前，强烈建议配置一个 [队列驱动](https://www.kancloud.cn/tonyyu/laravel_5_6/786248) 。运行一个队列来处理 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
~~~
## 配置
### 配置模型索引
每个Eloquent模型都是通过给定的搜索「索引」进行同步，该「索引」包含所有可搜索的模型记录。换句话说，你可以把每一个「索引」设想为一张 MySQL 数据表。默认情况下，每个模型都会被持久化到与模型的「表」名（通常是模型名称的复数形式）相匹配的索引。你也可以通过覆盖模型上的 `searchableAs` 方法来自定义模型的索引：
~~~
<?php
namespace App;
use Laravel\Scout\Searchable;
use Illuminate\Database\Eloquent\Model;
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;
use Laravel\Scout\Searchable;
use Illuminate\Database\Eloquent\Model;
class Post extends Model
{
use Searchable;
/**
* Get the indexable data array for the model.
*
* @return array
*/
public function toSearchableArray()
{
$array = $this->toArray();
// Customize array...
return $array;
}
}
~~~
## 索引
### 批量导入
如果你想安装Scout 到已存在的项目中，你可能已经有了想要导入搜索驱动的数据库记录。Scout 提供了 Artisan 命令 `import` 用来导入所有已存在的记录到搜索索引：
~~~
php artisan scout:import "App\Post"
~~~
### 添加记录
当你将 `Laravel\Scout\Searchable` trait 添加到模型中，你需要做的就是 `save` 一个模型实例，它将自动被添加到搜索索引。如果你已经将 Scout 配置为 [使用队列](https://www.kancloud.cn/tonyyu/laravel_5_6/786295#_38)，那这个操作会在后台由你的队列工作进程来执行：
~~~
$order = new App\Order;
// ...
$order->save();
~~~
#### 通过查询添加
如果你想通过 Eloquent 查询构造器将模型集合添加到搜索索引中，你也可以在 Eloquent 查询构造器上链式调用 `searchable` 方法。`searchable` 会把构造器的查询 [结果分块](https://www.kancloud.cn/tonyyu/laravel_5_6/786272#_194) 并且将记录添加到你的搜索索引里。同样的，如果你已经配置 Scout 为使用队列，则所有的数据块将在后台由你的队列工作进程添加：
~~~
// 通过 Eloquent 查询构造器增加...
App\Order::where('price', '>', 100)->searchable();
// 你也可以通过模型关系增加记录...
$user->orders()->searchable();
// 你也可以通过集合增加记录...
$orders->searchable();
~~~
`searchable` 方法可以被看做是「更新插入」的操作。换句话说，如果模型记录已经在你的索引里了，它就会被更新。如果搜索索引中不存在，则将其添加到索引中。
### 更新记录
要更新可搜索的模型，只需要更新模型实例的属性并将模型 `save` 到数据库。Scout 会自动将更新同步到你的搜索索引中：
~~~
$order = App\Order::find(1);
// Update the order...
$order->save();
~~~
你也可以在 Eloquent 查询语句上使用 `searchable` 方法来更新一个模型的集合。如果这个模型不存在你检索的索引里，就会被创建：
~~~
// Updating via Eloquent query...
App\Order::where('price', '>', 100)->searchable();
// You may also update via relationships...
$user->orders()->searchable();
// You may also update via collections...
$orders->searchable();
~~~
### 删除记录
简单地使用 `delete` 从数据库中删除该模型就可以移除索引里的记录。这种删除形式甚至与 [软删除]https://www.kancloud.cn/tonyyu/laravel_5_6/786272#_470) 的模型兼容:
~~~
$order = App\Order::find(1);
$order->delete();
~~~
如果你不想在删除记录之前检索模型，可以在 Eloquent 查询实例或集合上使用 `unsearchable` 方法：
~~~
// Removing via Eloquent query...
App\Order::where('price', '>', 100)->unsearchable();
// You may also remove via relationships...
$user->orders()->unsearchable();
// You may also remove via collections...
$orders->unsearchable();
~~~
### 暂停索引
你可能需要在执行一批 Eloquent 操作的时候，不同步模型数据到搜索索引。此时你可以使用 `withoutSyncingToSearch`方法来执行此操作。这个方法接受一个立即执行的回调。该回调中所有的操作都不会同步到模型的索引：
~~~
App\Order::withoutSyncingToSearch(function () {
// Perform model actions...
});
~~~
### 有条件地搜索模型实例
有时候你可能需要在某些条件下模型是可搜索的。例如，假设你有 `App\Post` 模型可能两种状态之一：「草稿」和「发布」。你可能只允许搜索 「发布」过的帖子。为了实现这一点，你可能要在你的模型中定义一个 `shouldBeSearchable`方法：
~~~
public function shouldBeSearchable()
{
return $this->isPublished();
}
~~~
## 搜索
你可以使用 `search` 方法来搜索模型。`search` 方法接受一个用于搜索模型的字符串。你还需在搜索查询上链式调用 `get` 方法，才能用给定的搜索语句查询与之匹配的 Eloquent 模型：
~~~
$orders = App\Order::search('Star Trek')->get();
~~~
Scout 搜索返回 Eloquent 模型的集合，因此你可以直接从路由或控制器返回结果，它们会被自动转换成 JSON 格式：
~~~
use Illuminate\Http\Request;
Route::get('/search', function (Request $request) {
return App\Order::search($request->search)->get();
});
~~~
如果你想在它们返回 Eloquent 模型前得到原结果，你应该使用`raw` 方法：
~~~
$orders = App\Order::search('Star Trek')->raw();
~~~
搜索查询通常会在模型的 [`searchableAs`](https://www.kancloud.cn/tonyyu/laravel_5_6/786295#_58) 方法指定的索引上执行。当然，你也可以使用 `within` 方法指定应该搜索的自定义索引：
~~~
$orders = App\Order::search('Star Trek')
->within('tv_shows_popularity_desc')
->get();
~~~
### Where 语句
允许你在搜索查询中增加简单的「where」语句。目前，这些语句只支持基本的数值等式检查，并且主要是用于根据拥有者的 ID 进行的范围搜索查询。由于搜索索引不是关系型数据库，因此当前不支持更高级的「where」语句：
~~~
$orders = App\Order::search('Star Trek')->where('user_id', 1)->get();
~~~
### 分页
除了检索模型的集合，你也可以使用 `paginate` 方法对搜索结果进行分页。这个方法会返回一个就像 [传统的 Eloquent 查询分页](https://www.kancloud.cn/tonyyu/laravel_5_6/786262) 一样的 `Paginator` 实例：
~~~
$orders = App\Order::search('Star Trek')->paginate();
~~~
你可以通过将数量作为第一个参数传递给 `paginate` 方法来指定每页检索多少个模型：
~~~
$orders = App\Order::search('Star Trek')->paginate(15);
~~~
获取到检索结果后，就可以使用 [Blade](https://www.kancloud.cn/tonyyu/laravel_5_6/786198) 来渲染分页链接从而显示结果，就像传统的 Eloquent 查询分页一样：
~~~
<div class="container">
@foreach ($orders as $order)
{{ $order->price }}
@endforeach
</div>
{{ $orders->links() }}
~~~
### 软删除
如果你的索引模型是 [软删除](https://www.kancloud.cn/tonyyu/laravel_5_6/786272#_470) ，并且你需要搜索软删除的模型，设置 `config/scout.php` 配置文件`soft_delete` 选项的值为 `true`：
~~~
'soft_delete' => true,
~~~
当这个配置选项是 `true`的时候， Scout 不会从搜索索引中移除软删除模型。相反，它会在索引记录中设置一个隐藏 `__soft_deleted` 属性。 然后，在搜索的时候，你可以使用 `withTrashed` 或 `onlyTrashed` 方法检索软删除记录：
~~~
// 搜索结果包括已删除的记录...
$orders = App\Order::withTrashed()->search('Star Trek')->get();
// 搜索结果只包含已删除的记录...
$orders = App\Order::onlyTrashed()->search('Star Trek')->get();
~~~
> {tip} 要永久删除模型可以使用 `forceDelete` 来删除，Scout 将自动的从搜索索引中移除模型。
## 自定义引擎
#### 写引擎
如果内置的 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($results, $model);
abstract public function getTotalCount($results);
~~~
在 `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',
~~~
- 前言
- 翻译说明
- 发行说明
- 升级指南
- 贡献导引
- 入门指南
- 安装
- 配置信息
- 文件夹结构
- Homestead
- Valet
- 部署
- 核心架构
- 请求周期
- 服务容器
- 服务提供者
- Facades
- Contracts
- 基础功能
- 路由
- 中间件
- CSRF 保护
- 控制器
- 请求
- 响应
- 视图
- URL
- Session
- 表单验证
- 错误
- 日志
- 前端开发
- Blade 模板
- 本地化
- 前端指南
- 编辑资源 Mix
- 安全相关
- 用户认证
- Passport OAuth 认证
- 用户授权
- 加密解密
- 哈希
- 重置密码
- 综合话题
- Artisan 命令行
- 广播系统
- 缓存系统
- 集合
- 事件系统
- 文件存储
- 辅助函数
- 邮件发送
- 消息通知
- 扩展包开发
- 队列
- 任务调度
- 数据库
- 快速入门
- 查询构造器
- 分页
- 数据库迁移
- 数据填充
- Redis
- Eloquent ORM
- 快速入门
- 模型关联
- Eloquent 集合
- 修改器
- API 资源
- 序列化
- 测试相关
- 快速入门
- HTTP 测试
- 浏览器测试 Dusk
- 数据库测试
- 测试模拟器
- 官方扩展包
- Cashier 交易工具包
- Envoy 部署工具
- Horizon
- Scout 全文搜索
- Socialite 社会化登录