# Laravel Scout - [简介](#introduction) - [安装](#installation) - [队列](#queueing) - [驱动的先决条件](#driver-prerequisites) - [配置](#configuration) - [配置模型索引](#configuring-model-indexes) - [配置可搜索数据](#configuring-searchable-data) - [配置模型 ID](#configuring-the-model-id) - [识别用户](#identifying-users) - [索引](#indexing) - [批量导入](#batch-import) - [添加记录](#adding-records) - [更新记录](#updating-records) - [删除记录](#removing-records) - [暂停索引](#pausing-indexing) - [有条件的可搜索模型实例](#conditionally-searchable-model-instances) - [搜索](#searching) - [Where 条件](#where-clauses) - [分页](#pagination) - [软删除](#soft-deleting) - [自定义引擎的搜索](#customizing-engine-searches) - [自定义引擎](#custom-engines) - [生成器宏](#builder-macros) ## 简介 Laravel Scout 为 [Eloquent 模型](/docs/laravel/8.x/eloquent) 的全文搜索提供了基于驱动的简单的解决方案。通过使用模型观察者, Scout 会自动同步 Eloquent 记录的搜索索引。 目前, Scout 自带一个 [Algolia](https://www.algolia.com/) 驱动。不过,编写自定义驱动也很简单,你可以轻松的通过自己的搜索实现来扩展 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 会注册一个模型观察者来保持模型和所有驱动的同步: ### 队列 尽管 Scout 并不强制需要使用队列,但是在使用这个库之前,强烈建议你配置一个 [队列驱动](/docs/laravel/8.x/queues),使用它运行一个队列来处理允许 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` 方法来自定义模型的索引: ### 配置可搜索数据 默认情况下,模型以完整的 `toArray` 格式持久化到搜索索引。如果要自定义同步到搜索索引的数据,可以覆盖模型上的 `toSearchableArray` 方法: toArray(); // 自定义数组... return $array; } } ### 配置模型ID 默认情况下,Scout 将使用模型的主键作为搜索索引中存储的唯一 ID 。 可以通过模型上的 `getScoutKey` 和 `getScoutKeyName` 方法自定义: 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 配置为 [使用队列](#queueing),那这个操作会在后台由你的队列工作进程来执行: $order = new App\Models\Order; // ... $order->save(); #### 通过查询添加 如果你想通过 Eloquent 查询构造器将模型集合添加到搜索索引中,你也可以在 Eloquent 查询构造器上链式调用 `searchable` 方法。`searchable` 会把构造器的查询 [结果分块](/docs/laravel/8.x/eloquent#chunking-results) 并且将记录添加到你的搜索索引里。同样的,如果你已经配置 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` 从数据库中删除该模型就可以移除索引里的记录。这种删除形式甚至与 [软删除](/docs/laravel/8.x/eloquent#soft-deleting) 的模型兼容: $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`](#configuring-model-indexes) 方法指定的索引上执行。当然,你也可以使用 `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 查询分页 ](/docs/laravel/8.x/pagination) 一样的 `Paginator` 实例: $orders = App\Models\Order::search('Star Trek')->paginate(); 你可以通过将数量作为第一个参数传递给 `paginate` 方法来指定每页检索多少个模型: $orders = App\Models\Order::search('Star Trek')->paginate(15); 检索结果后,您可以显示结果并使用[Blade](/ docs / laravel / 8.x / blade)呈现页面链接,就好像你对传统的Eloquent查询进行了分页一样: