跳至内容

Laravel Scout

介绍

Laravel Scout提供了一个简单、基于驱动程序的解决方案，用于为你的Eloquent 模型添加全文搜索功能。使用模型观察器，Scout 会自动保持你的搜索索引与 Eloquent 记录同步。

目前，Scout 已集成Algolia、Meilisearch、Typesense以及 MySQL / PostgreSQL ( database) 驱动程序。此外，Scout 还包含一个专为本地开发使用而设计的“集合”驱动程序，无需任何外部依赖项或第三方服务。此外，编写自定义驱动程序非常简单，您可以自由地使用自己的搜索实现来扩展 Scout。

安装

首先，通过 Composer 包管理器安装 Scout：

1composer require laravel/scout

安装 Scout 后，你应该使用 Artisan 命令发布 Scout 配置文件vendor:publish。此命令会将scout.php配置文件发布到你的应用程序config目录：

1php artisan vendor:publish --provider="Laravel\Scout\ScoutServiceProvider"

最后，将Laravel\Scout\Searchable特征添加到您想要搜索的模型中。此特征将注册一个模型观察器，该观察器会自动使模型与您的搜索驱动程序保持同步：

 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6use Laravel\Scout\Searchable;
 7 
 8class Post extends Model
 9{
10    use Searchable;
11}

排队

虽然 Scout 并非强制使用，但在使用该库之前，强烈建议您配置队列驱动程序。运行队列工作器将允许 Scout 将所有将模型信息同步到搜索索引的操作加入队列，从而显著缩短应用程序的 Web 界面响应时间。

配置队列驱动程序后，将配置文件queue中的选项值设置config/scout.php为true：

1'queue' => true,

即使将queue选项设置为false，也请务必记住，某些 Scout 驱动程序（例如 Algolia 和 Meil​​isearch）始终会异步索引记录。这意味着，即使索引操作已在 Laravel 应用程序中完成，搜索引擎本身也可能无法立即反映新的和更新的记录。

要指定 Scout 作业使用的连接和队列，您可以将queue配置选项定义为数组：

1'queue' => [
2    'connection' => 'redis',
3    'queue' => 'scout'
4],

当然，如果您自定义 Scout 作业使用的连接和队列，则应该运行队列工作器来处理该连接和队列上的作业：

1php artisan queue:work redis --queue=scout

驱动程序先决条件

阿尔及利亚

使用 Algolia 驱动程序时，您需要在配置文件中配置 Algoliaid和secret凭据config/scout.php。配置凭据后，您还需要通过 Composer 包管理器安装 Algolia PHP SDK：

1composer require algolia/algoliasearch-client-php

美丽搜索

Meilisearch是一款速度超快的开源搜索引擎。如果您不确定如何在本地计算机上安装 Meil​​isearch，可以使用Laravel Sail，这是 Laravel 官方支持的 Docker 开发环境。

使用 Meil​​isearch 驱动程序时，您需要通过 Composer 包管理器安装 Meil​​isearch PHP SDK：

1composer require meilisearch/meilisearch-php http-interop/http-factory-guzzle

然后，在应用程序文件中设置SCOUT_DRIVER环境变量以及 Meil​​isearchhost和凭据：key.env

1SCOUT_DRIVER=meilisearch
2MEILISEARCH_HOST=http://127.0.0.1:7700
3MEILISEARCH_KEY=masterKey

有关 Meil​​isearch 的更多信息，请参阅Meil​​isearch 文档。

此外，您应查看Meil​​isearch 关于二进制兼容性的文档meilisearch/meilisearch-php，以确保安装的版本与您的 Meil​​isearch 二进制版本兼容。

在使用 Meil​​isearch 的应用程序上升级 Scout 时，您应该始终检查Meil​​isearch 服务本身的任何其他重大更改。

Typesense

Typesense是一款速度极快的开源搜索引擎，支持关键字搜索、语义搜索、地理搜索和矢量搜索。

您可以自行托管Typesense 或使用Typesense Cloud。

要开始将 Typesense 与 Scout 结合使用，请通过 Composer 包管理器安装 Typesense PHP SDK：

1composer require typesense/typesense-php

然后，在应用程序的 .env 文件中设置SCOUT_DRIVER环境变量以及 Typesense 主机和 API 密钥凭据：

1SCOUT_DRIVER=typesense
2TYPESENSE_API_KEY=masterKey
3TYPESENSE_HOST=localhost

如果你使用的是Laravel Sail，则可能需要调整TYPESENSE_HOST环境变量以匹配 Docker 容器名称。你还可以选择指定安装的端口、路径和协议：

1TYPESENSE_PORT=8108
2TYPESENSE_PATH=
3TYPESENSE_PROTOCOL=http

您可以在应用程序的配置文件中找到 Typesense 集合的其他设置和架构定义config/scout.php。有关 Typesense 的更多信息，请参阅Typesense 文档。

在 Typesense 中准备存储数据

当使用 Typesense 时，您的可搜索模型必须定义一种toSearchableArray方法，将模型的主键转换为字符串，将创建日期转换为 UNIX 时间戳：

 1/**
 2 * Get the indexable data array for the model.
 3 *
 4 * @return array<string, mixed>
 5 */
 6public function toSearchableArray(): array
 7{
 8    return array_merge($this->toArray(),[
 9        'id' => (string) $this->id,
10        'created_at' => $this->created_at->timestamp,
11    ]);
12}

您还应该在应用程序config/scout.php文件中定义 Typesense 集合模式。集合模式描述了可通过 Typesense 搜索的每个字段的数据类型。有关所有可用模式选项的更多信息，请参阅Typesense 文档。

如果您需要在定义 Typesense 集合后更改其架构，您可以运行scout:flush和scout:import，这将删除所有现有的索引数据并重新创建架构。或者，您可以使用 Typesense 的 API 来修改集合的架构，而无需删除任何索引数据。

如果您的可搜索模型是软可删除的，则应__soft_deleted在应用程序的配置文件中在模型对应的 Typesense 模式中定义一个字段config/scout.php：

 1User::class => [
 2    'collection-schema' => [
 3        'fields' => [
 4            // ...
 5            [
 6                'name' => '__soft_deleted',
 7                'type' => 'int32',
 8                'optional' => true,
 9            ],
10        ],
11    ],
12],

动态搜索参数

Typesense 允许您通过下列方法执行搜索操作时动态修改搜索参数options：

1use App\Models\Todo;
2 
3Todo::search('Groceries')->options([
4    'query_by' => 'title, description'
5])->get();

配置

配置模型索引

每个 Eloquent 模型都与一个指定的搜索“索引”同步，该索引包含该模型的所有可搜索记录。换句话说，您可以将每个索引想象成一个 MySQL 表。默认情况下，每个模型都会被持久化到与其典型“表”名称匹配的索引中。通常，这是模型名称的复数形式；但是，您可以通过覆盖searchableAs模型上的方法来自定义模型的索引：

 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6use Laravel\Scout\Searchable;
 7 
 8class Post extends Model
 9{
10    use Searchable;
11 
12    /**
13     * Get the name of the index associated with the model.
14     */
15    public function searchableAs(): string
16    {
17        return 'posts_index';
18    }
19}

配置可搜索数据

默认情况下，给定模型的完整toArray表单将持久化到其搜索索引中。如果您想自定义同步到搜索索引的数据，可以重写toSearchableArray模型上的以下方法：

 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6use Laravel\Scout\Searchable;
 7 
 8class Post extends Model
 9{
10    use Searchable;
11 
12    /**
13     * Get the indexable data array for the model.
14     *
15     * @return array<string, mixed>
16     */
17    public function toSearchableArray(): array
18    {
19        $array = $this->toArray();
20 
21        // Customize the data array...
22 
23        return $array;
24    }
25}

某些搜索引擎（例如美丽搜索）仅对正确类型的数据执行过滤操作（>、<等）。因此，在使用这些搜索引擎并自定义可搜索数据时，应确保将数值转换为正确的类型：

1public function toSearchableArray()
2{
3    return [
4        'id' => (int) $this->id,
5        'name' => $this->name,
6        'price' => (float) $this->price,
7    ];
8}

配置索引设置（Algolia）

config/scout.php有时，您可能需要在 Algolia 索引上配置其他设置。虽然您可以通过 Algolia UI 管理这些设置，但有时直接从应用程序的配置文件管理索引配置的所需状态会更高效。

这种方法允许您通过应用程序的自动部署流水线部署这些设置，从而避免手动配置并确保跨多个环境的一致性。您可以配置可过滤属性、排名、分面或任何其他受支持的设置。

首先，在应用程序的config/scout.php配置文件中为每个索引添加设置：

 1use App\Models\User;
 2use App\Models\Flight;
 3 
 4'algolia' => [
 5    'id' => env('ALGOLIA_APP_ID', ''),
 6    'secret' => env('ALGOLIA_SECRET', ''),
 7    'index-settings' => [
 8        User::class => [
 9            'searchableAttributes' => ['id', 'name', 'email'],
10            'attributesForFaceting'=> ['filterOnly(email)'],
11            // Other settings fields...
12        ],
13        Flight::class => [
14            'searchableAttributes'=> ['id', 'destination'],
15        ],
16    ],
17],

如果给定索引对应的模型是可软删除的，并且包含在数组中，Scout 将自动支持对该索引上的软删除模型进行分面。如果没有其他分面属性需要为可软删除的模型索引定义，则只需在该模型的数组index-settings中添加一个空条目即可：index-settings

1'index-settings' => [
2    Flight::class => []
3],

配置应用程序的索引设置后，必须调用scout:sync-index-settingsArtisan 命令。此命令将告知 Algolia 您当前配置的索引设置。为了方便起见，您可能希望将此命令作为部署过程的一部分：

1php artisan scout:sync-index-settings

配置可过滤数据和索引设置（Meilisearch）

与 Scout 的其他驱动程序不同，Meilisearch 要求您预先定义索引搜索设置，例如可过滤属性、可排序属性和其他支持的设置字段。

可过滤属性是指您在调用 Scoutwhere方法时计划过滤的任何属性，而可排序属性是指您在调用 ScoutorderBy方法时计划排序的任何属性。要定义索引设置，请在应用的配置文件中调整配置条目index-settings的部分内容：meilisearchscout

 1use App\Models\User;
 2use App\Models\Flight;
 3 
 4'meilisearch' => [
 5    'host' => env('MEILISEARCH_HOST', 'http://localhost:7700'),
 6    'key' => env('MEILISEARCH_KEY', null),
 7    'index-settings' => [
 8        User::class => [
 9            'filterableAttributes'=> ['id', 'name', 'email'],
10            'sortableAttributes' => ['created_at'],
11            // Other settings fields...
12        ],
13        Flight::class => [
14            'filterableAttributes'=> ['id', 'destination'],
15            'sortableAttributes' => ['updated_at'],
16        ],
17    ],
18],

如果给定索引所依赖的模型是可软删除的，并且包含在index-settings数组中，Scout 将自动支持在该索引上筛选软删除的模型。如果您没有为可软删除的模型索引定义其他可过滤或可排序的属性，则只需在index-settings该模型的数组中添加一个空条目即可：

1'index-settings' => [
2    Flight::class => []
3],

配置应用程序的索引设置后，必须调用scout:sync-index-settingsArtisan 命令。此命令会将您当前的索引设置告知 Meil​​isearch。为了方便起见，您可能希望将此命令作为部署过程的一部分：

1php artisan scout:sync-index-settings

配置模型ID

默认情况下，Scout 将使用模型的主键作为模型的唯一 ID/键，存储在搜索索引中。如果需要自定义此行为，可以重写模型上的getScoutKey和方法：getScoutKeyName

 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6use Laravel\Scout\Searchable;
 7 
 8class User extends Model
 9{
10    use Searchable;
11 
12    /**
13     * Get the value used to index the model.
14     */
15    public function getScoutKey(): mixed
16    {
17        return $this->email;
18    }
19 
20    /**
21     * Get the key name used to index the model.
22     */
23    public function getScoutKeyName(): mixed
24    {
25        return 'email';
26    }
27}

配置每个模型的搜索引擎

在搜索时，Scout 通常会使用应用程序配置文件中指定的默认搜索引擎。但是，可以通过重写模型上的方法scout来更改特定模型的搜索引擎：searchableUsing

 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6use Laravel\Scout\Engines\Engine;
 7use Laravel\Scout\EngineManager;
 8use Laravel\Scout\Searchable;
 9 
10class User extends Model
11{
12    use Searchable;
13 
14    /**
15     * Get the engine used to index the model.
16     */
17    public function searchableUsing(): Engine
18    {
19        return app(EngineManager::class)->engine('meilisearch');
20    }
21}

识别用户

Scout 还允许您在使用Algolia时自动识别用户。在 Algolia 的仪表板中查看搜索分析时，将经过身份验证的用户与搜索操作关联起来可能会很有帮助。您可以通过在应用程序文件中定义SCOUT_IDENTIFY环境变量来启用用户识别：true.env

1SCOUT_IDENTIFY=true

启用此功能还会将请求的 IP 地址和经过身份验证的用户的主要标识符传递给 Algolia，以便这些数据与用户发出的任何搜索请求相关联。

数据库/集合引擎

数据库引擎

数据库引擎目前支持MySQL和PostgreSQL。

如果您的应用程序与中小型数据库交互，或者负载较轻，那么使用 Scout 的“数据库”引擎可能会更方便。该数据库引擎会在筛选现有数据库中的结果时使用“where like”子句和全文索引，以确定适合您查询的搜索结果。

SCOUT_DRIVER要使用数据库引擎，您可以简单地将环境变量的值设置为，或者直接在应用程序的配置文件中database指定驱动程序：databasescout

1SCOUT_DRIVER=database

将数据库引擎指定为首选驱动程序后，您必须配置可搜索数据。然后，您就可以开始针对模型执行搜索查询。使用数据库引擎时，无需搜索引擎索引（例如，为 Algolia、Meilisearch 或 Typesense 建立种子所需的索引）。

自定义数据库搜索策略

默认情况下，数据库引擎会针对您配置为可搜索的每个模型属性执行“where like”查询。然而，在某些情况下，这可能会导致性能不佳。因此，您可以配置数据库引擎的搜索策略，使某些指定的列使用全文搜索查询，或者仅使用“where like”约束来搜索字符串的前缀（example%），而不是在整个字符串内搜索（%example%）。

要定义此行为，您可以将 PHP 属性分配给模型的toSearchableArray方法。任何未分配附加搜索策略行为的列将继续使用默认的“where like”策略：

 1use Laravel\Scout\Attributes\SearchUsingFullText;
 2use Laravel\Scout\Attributes\SearchUsingPrefix;
 3 
 4/**
 5 * Get the indexable data array for the model.
 6 *
 7 * @return array<string, mixed>
 8 */
 9#[SearchUsingPrefix(['id', 'email'])]
10#[SearchUsingFullText(['bio'])]
11public function toSearchableArray(): array
12{
13    return [
14        'id' => $this->id,
15        'name' => $this->name,
16        'email' => $this->email,
17        'bio' => $this->bio,
18    ];
19}

在指定某个列应该使用全文查询约束之前，请确保该列已被分配了全文索引。

收集引擎

虽然您可以在本地开发过程中自由使用 Algolia、Meilisearch 或 Typesense 搜索引擎，但您可能会发现使用“collection”引擎会更方便。该引擎会使用“where”子句和集合筛选条件，对现有数据库中的结果进行筛选，以确定适合您查询的搜索结果。使用此引擎时，无需“索引”可搜索的模型，因为它们会直接从本地数据库中检索。

SCOUT_DRIVER要使用收集引擎，您可以简单地将环境变量的值设置为，或者直接在应用程序的配置文件中collection指定驱动程序：collectionscout

1SCOUT_DRIVER=collection

将集合驱动程序指定为首选驱动程序后，即可开始针对模型执行搜索查询。使用集合引擎时，无需搜索引擎索引（例如，用于Seeding Algolia、Meilisearch 或 Typesense 索引所需的索引）。

与数据库引擎的区别

乍一看，“数据库”和“集合”引擎非常相似。它们都直接与数据库交互以检索搜索结果。但是，集合引擎不会使用全文索引或LIKE子句来查找匹配的记录。相反，它会提取所有可能的记录，并使用 Laravel 的Str::is辅助函数来判断搜索字符串是否存在于模型属性值中。

收集引擎是最具可移植性的搜索引擎，因为它可以在 Laravel 支持的所有关系数据库（包括 SQLite 和 SQL Server）上运行；但是，它的效率低于 Scout 的数据库引擎。

索引

批量导入

如果您要将 Scout 安装到现有项目中，则可能已经有一些需要导入到索引中的数据库记录。Scout 提供了一个scout:importArtisan 命令，您可以使用该命令将所有现有记录导入到搜索索引中：

1php artisan scout:import "App\Models\Post"

该flush命令可用于从搜索索引中删除模型的所有记录：

1php artisan scout:flush "App\Models\Post"

修改导入查询

如果您想修改用于检索所有模型以进行批量导入的查询，您可以makeAllSearchableUsing在模型上定义一个方法。这是一个很好的地方，可以在导入模型之前添加任何可能需要的即时关系加载：

1use Illuminate\Database\Eloquent\Builder;
2 
3/**
4 * Modify the query used to retrieve models when making all of the models searchable.
5 */
6protected function makeAllSearchableUsing(Builder $query): Builder
7{
8    return $query->with('author');
9}

该makeAllSearchableUsing方法在使用队列批量导入模型时可能不适用。当作业处理模型集合时，关系不会恢复。

添加记录

将特征添加Laravel\Scout\Searchable到模型后，您只需创建save一个create模型实例，它就会自动添加到您的搜索索引中。如果您已将 Scout 配置为使用队列，则此操作将由您的队列工作器在后台执行：

1use App\Models\Order;
2 
3$order = new Order;
4 
5// ...
6 
7$order->save();

通过查询添加记录

如果您想通过 Eloquent 查询将一系列模型添加到搜索索引中，可以将该searchable方法链接到 Eloquent 查询上。该searchable方法会将查询结果分块，并将记录添加到搜索索引中。同样，如果您已将 Scout 配置为使用队列，则所有分块都将由队列工作器在后台导入：

1use App\Models\Order;
2 
3Order::where('price', '>', 100)->searchable();

您也可以searchable在 Eloquent 关系实例上调用该方法：

1$user->orders()->searchable();

或者，如果您已经在内存中有一个 Eloquent 模型集合，您可以调用searchable集合实例上的方法将模型实例添加到其相应的索引中：

1$orders->searchable();

该searchable方法可以被视为“upsert”操作。换句话说，如果模型记录已存在于索引中，则会更新该记录。如果该记录不存在于搜索索引中，则会将其添加到索引中。

更新记录

要更新可搜索模型，你只需更新模型实例的属性并将save模型更新到数据库中。Scout 会自动将更改保存到你的搜索索引中：

1use App\Models\Order;
2 
3$order = Order::find(1);
4 
5// Update the order...
6 
7$order->save();

你也可以searchable在 Eloquent 查询实例上调用该方法来更新模型集合。如果搜索索引中不存在这些模型，则会创建它们：

1Order::where('price', '>', 100)->searchable();

如果您想要更新关系中所有模型的搜索索引记录，您可以searchable在关系实例上调用：

1$user->orders()->searchable();

或者，如果您已经在内存中拥有一个 Eloquent 模型集合，则可以调用searchable集合实例上的方法来更新其相应索引中的模型实例：

1$orders->searchable();

导入前修改记录

有时，您可能需要在模型集合可供搜索之前对其进行准备。例如，您可能希望预先加载某个关系，以便能够高效地将关系数据添加到搜索索引中。为此，请makeSearchableUsing在相应的模型上定义一个方法：

1use Illuminate\Database\Eloquent\Collection;
2 
3/**
4 * Modify the collection of models being made searchable.
5 */
6public function makeSearchableUsing(Collection $models): Collection
7{
8    return $models->load('author');
9}

删除记录

要从索引中删除一条记录，只需delete从数据库中删除该模型即可。即使你使用的是软删除模型，也可以这样做：

1use App\Models\Order;
2 
3$order = Order::find(1);
4 
5$order->delete();

如果您不想在删除记录之前检索模型，您可以unsearchable在 Eloquent 查询实例上使用该方法：

1Order::where('price', '>', 100)->unsearchable();

如果您想要删除关系中所有模型的搜索索引记录，您可以unsearchable在关系实例上调用：

1$user->orders()->unsearchable();

或者，如果您已经在内存中有一个 Eloquent 模型集合，则可以调用unsearchable集合实例上的方法从其相应的索引中删除模型实例：

1$orders->unsearchable();

要从相应的索引中删除所有模型记录，您可以调用该removeAllFromSearch方法：

1Order::removeAllFromSearch();

暂停索引

有时您可能需要对模型执行一批 Eloquent 操作，但又不想将模型数据同步到搜索索引。您可以使用withoutSyncingToSearch方法来执行此操作。此方法接受一个闭包，该闭包会立即执行。任何在闭包内执行的模型操作都不会同步到模型的索引：

1use App\Models\Order;
2 
3Order::withoutSyncingToSearch(function () {
4    // Perform model actions...
5});

有条件搜索的模型实例

有时你可能需要仅在特定条件下使模型可搜索。例如，假设你的模型可能处于两种状态之一：“草稿”和“已发布”。你可能只希望“已发布”的帖子可搜索。为此，你可以在模型上App\Models\Post定义一个方法：shouldBeSearchable

1/**
2 * Determine if the model should be searchable.
3 */
4public function shouldBeSearchable(): bool
5{
6    return $this->isPublished();
7}

该shouldBeSearchable方法仅适用于通过save和create方法、查询或关系操作模型的情况。直接使用该searchable方法使模型或集合可搜索将覆盖该方法的结果shouldBeSearchable。

此shouldBeSearchable方法在使用 Scout 的“数据库”引擎时不适用，因为所有可搜索数据始终存储在数据库中。要在使用数据库引擎时实现类似的行为，您应该改用where 子句。

搜索

你可以使用 方法来搜索模型search。search 方法接受一个字符串，用于搜索你的模型。然后，你可以将该get方法链接到搜索查询上，以检索与给定搜索查询匹配的 Eloquent 模型：

1use App\Models\Order;
2 
3$orders = Order::search('Star Trek')->get();

由于 Scout 搜索返回的是 Eloquent 模型的集合，您甚至可以直接从路由或控制器返回结果，并且它们将自动转换为 JSON：

1use App\Models\Order;
2use Illuminate\Http\Request;
3 
4Route::get('/search', function (Request $request) {
5    return Order::search($request->search)->get();
6});

如果您希望在将原始搜索结果转换为 Eloquent 模型之前获取它们，您可以使用该raw方法：

1$orders = Order::search('Star Trek')->raw();

自定义索引

搜索查询通常会根据模型的searchableAs方法指定的索引执行。不过，你也可以使用该within方法指定要搜索的自定义索引：

1$orders = Order::search('Star Trek')
2    ->within('tv_shows_popularity_desc')
3    ->get();

Where 子句

Scout 允许您在搜索查询中添加简单的“where”子句。目前，这些子句仅支持基本的数值相等性检查，主要用于根据所有者 ID 确定搜索查询的范围：

1use App\Models\Order;
2 
3$orders = Order::search('Star Trek')->where('user_id', 1)->get();

此外，该whereIn方法可用于验证给定列的值是否包含在给定数组中：

1$orders = Order::search('Star Trek')->whereIn(
2    'status', ['open', 'paid']
3)->get();

该whereNotIn方法验证给定列的值不包含在给定数组中：

1$orders = Order::search('Star Trek')->whereNotIn(
2    'status', ['closed']
3)->get();

由于搜索索引不是关系数据库，因此目前不支持更高级的“where”子句。

如果您的应用程序正在使用 Meil​​isearch，则在使用 Scout 的“where”子句之前， 您必须配置应用程序的可过滤属性。

分页

除了检索模型集合之外，您还可以使用paginate方法来对搜索结果进行分页。此方法将返回一个Illuminate\Pagination\LengthAwarePaginator实例，就像您对传统的 Eloquent 查询进行了分页一样：

1use App\Models\Order;
2 
3$orders = Order::search('Star Trek')->paginate();

您可以通过将数量作为第一个参数传递给paginate方法来指定每页检索多少个模型：

1$orders = Order::search('Star Trek')->paginate(15);

检索到结果后，您可以使用Blade显示结果并呈现页面链接，就像对传统的 Eloquent 查询进行分页一样：

1<div class="container">
2    @foreach ($orders as $order)
3        {{ $order->price }}
4    @endforeach
5</div>
6 
7{{ $orders->links() }}

当然，如果您希望以 JSON 格式检索分页结果，您可以直接从路由或控制器返回分页器实例：

1use App\Models\Order;
2use Illuminate\Http\Request;
3 
4Route::get('/orders', function (Request $request) {
5    return Order::search($request->input('query'))->paginate(15);
6});

由于搜索引擎无法识别 Eloquent 模型的全局作用域定义，因此在使用 Scout 分页功能的应用中，不应使用全局作用域。或者，在使用 Scout 搜索时，您应该重新创建全局作用域的约束。

软删除

如果您的索引模型是软删除的，并且您需要搜索软删除的模型，请将配置文件soft_delete的选项设置config/scout.php为true：

1'soft_delete' => true,

当此配置选项为 时true，Scout 不会从搜索索引中移除软删除的模型。相反，它会__soft_deleted在索引记录上设置一个隐藏属性。然后，你可以在搜索时使用withTrashed或onlyTrashed方法检索软删除的记录：

1use App\Models\Order;
2 
3// Include trashed records when retrieving results...
4$orders = Order::search('Star Trek')->withTrashed()->get();
5 
6// Only include trashed records when retrieving results...
7$orders = Order::search('Star Trek')->onlyTrashed()->get();

当使用永久删除软删除模型时forceDelete，Scout 将自动将其从搜索索引中删除。

自定义引擎搜索

如果您需要对引擎的搜索行为进行高级自定义，可以将闭包作为第二个参数传递给该search方法。例如，您可以使用此回调在搜索查询传递给 Algolia 之前将地理位置数据添加到您的搜索选项中：

 1use Algolia\AlgoliaSearch\SearchIndex;
 2use App\Models\Order;
 3 
 4Order::search(
 5    'Star Trek',
 6    function (SearchIndex $algolia, string $query, array $options) {
 7        $options['body']['query']['bool']['filter']['geo_distance'] = [
 8            'distance' => '1000km',
 9            'location' => ['lat' => 36, 'lon' => 111],
10        ];
11 
12        return $algolia->search($query, $options);
13    }
14)->get();

自定义 Eloquent 结果查询

Scout 从应用程序的搜索引擎中检索到匹配的 Eloquent 模型列表后，将使用 Eloquent 通过主键检索所有匹配的模型。您可以通过调用该query方法自定义此查询。该query方法接受一个闭包，该闭包将接收 Eloquent 查询构建器实例作为参数：

1use App\Models\Order;
2use Illuminate\Database\Eloquent\Builder;
3 
4$orders = Order::search('Star Trek')
5    ->query(fn (Builder $query) => $query->with('invoices'))
6    ->get();

由于此回调是在从应用程序的搜索引擎检索到相关模型后调用的，因此该query方法不应用于“过滤”结果。相反，您应该使用Scout where 子句。

定制引擎

编写引擎

如果 Scout 内置的搜索引擎无法满足您的需求，您可以编写自定义引擎并将其注册到 Scout。您的引擎应该扩展Laravel\Scout\Engines\Engine抽象类。此抽象类包含八个自定义引擎必须实现的方法：

 1use Laravel\Scout\Builder;
 2 
 3abstract public function update($models);
 4abstract public function delete($models);
 5abstract public function search(Builder $builder);
 6abstract public function paginate(Builder $builder, $perPage, $page);
 7abstract public function mapIds($results);
 8abstract public function map(Builder $builder, $results, $model);
 9abstract public function getTotalCount($results);
10abstract public function flush($model);

回顾一下这些方法在类中的实现可能会很有帮助Laravel\Scout\Engines\AlgoliaEngine。本课程将为你提供一个良好的起点，帮助你学习如何在自己的引擎中实现这些方法。

注册引擎

编写自定义引擎后，您可以使用extendScout 引擎管理器的方法将其注册到 Scout。Scout 的引擎管理器可以通过 Laravel 服务容器进行解析。您应该extend从boot类的方法App\Providers\AppServiceProvider或应用程序使用的任何其他服务提供者中调用该方法：

 1use App\ScoutExtensions\MySqlSearchEngine;
 2use Laravel\Scout\EngineManager;
 3 
 4/**
 5 * Bootstrap any application services.
 6 */
 7public function boot(): void
 8{
 9    resolve(EngineManager::class)->extend('mysql', function () {
10        return new MySqlSearchEngine;
11    });
12}

一旦你的引擎注册完毕，你就可以driver在应用程序的config/scout.php配置文件中将其指定为默认的 Scout：

1'driver' => 'mysql',