Laravel 中文文档

主题

Laravel Scout ​

简介 ​

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

Scout 内置了一个 database 引擎，使用 MySQL / PostgreSQL 全文索引和 LIKE 子句来搜索你的现有数据库——无需外部服务。对于大多数应用程序，这就是你所需要的。有关 Laravel 中所有可用搜索选项的概述，请查阅搜索文档。

Scout 还包含了 Algolia、Meilisearch 和 Typesense 的驱动，当你需要拼写容错、分面过滤或大规模地理搜索等功能时可以使用。还提供了一个用于本地开发的「collection」驱动，你也可以自由编写自定义引擎。

安装 ​

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

shell
composer require laravel/scout

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

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

最后，将 Laravel\Scout\Searchable trait 添加到你希望可搜索的模型中。此 trait 将注册一个模型观察者，自动保持模型与搜索驱动同步：

php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;

class Post extends Model
{
    use Searchable;
}

队列 ​

当使用非 database 或 collection 引擎时，你应该强烈考虑在使用该库之前配置一个队列驱动。运行队列 worker 将允许 Scout 将所有同步模型信息到搜索索引的操作排入队列，从而为应用程序的 Web 界面提供更好的响应时间。

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

php
'queue' => true,

即使 queue 选项设置为 false，重要的是要记住一些 Scout 驱动（如 Algolia 和 Meilisearch）始终异步索引记录。换句话说，即使索引操作已在你的 Laravel 应用程序中完成，搜索引擎本身可能不会立即反映新的和更新的记录。

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

php
'queue' => [
    'connection' => 'redis',
    'queue' => 'scout'
],

当然，如果你自定义了 Scout 任务使用的连接和队列，你应该运行队列 worker 来处理该连接和队列上的任务：

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

驱动先决条件 ​

Algolia ​

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

shell
composer require algolia/algoliasearch-client-php

Meilisearch ​

Meilisearch 是一个快速的开源搜索引擎。如果你不确定如何在本地机器上安装 Meilisearch，你可以使用 Laravel Sail，Laravel 官方支持的 Docker 开发环境。

使用 Meilisearch 驱动时，你需要通过 Composer 包管理器安装 Meilisearch PHP SDK：

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

然后，在应用程序的 .env 文件中设置 SCOUT_DRIVER 环境变量以及你的 Meilisearch host 和 key 凭据：

ini
SCOUT_DRIVER=meilisearch
MEILISEARCH_HOST=http://127.0.0.1:7700
MEILISEARCH_KEY=masterKey

有关 Meilisearch 的更多信息，请查阅 Meilisearch 文档。

此外，你应该通过查看 Meilisearch 关于二进制兼容性的文档来确保安装与你的 Meilisearch 二进制版本兼容的 meilisearch/meilisearch-php 版本。

WARNING

在使用 Meilisearch 的应用程序上升级 Scout 时，你应该始终查看 Meilisearch 服务本身的任何其他破坏性更改。

Typesense ​

Typesense 是一个超快的开源搜索引擎，支持关键词搜索、语义搜索、地理搜索和向量搜索。

你可以自托管 Typesense 或使用 Typesense Cloud。

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

shell
composer require typesense/typesense-php

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

ini
SCOUT_DRIVER=typesense
TYPESENSE_API_KEY=masterKey
TYPESENSE_HOST=localhost

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

ini
TYPESENSE_PORT=8108
TYPESENSE_PATH=
TYPESENSE_PROTOCOL=http

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

配置 ​

配置可搜索数据 ​

默认情况下，给定模型的整个 toArray 形式将被持久化到其搜索索引中。如果你想自定义同步到搜索索引的数据，你可以覆盖模型上的 toSearchableArray 方法：

php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;

class Post extends Model
{
    use Searchable;

    /**
     * 获取模型的可索引数据数组。
     *
     * @return array<string, mixed>
     */
    public function toSearchableArray(): array
    {
        $array = $this->toArray();

        // 自定义数据数组...

        return $array;
    }
}

配置模型引擎 ​

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

php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Engines\Engine;
use Laravel\Scout\Scout;
use Laravel\Scout\Searchable;

class User extends Model
{
    use Searchable;

    /**
     * 获取用于索引模型的引擎。
     */
    public function searchableUsing(): Engine
    {
        return Scout::engine('meilisearch');
    }
}

Database / Collection 引擎 ​

Database 引擎 ​

WARNING

Database 引擎目前支持 MySQL 和 PostgreSQL，两者都提供对快速全文列索引的支持。

database 引擎使用 MySQL / PostgreSQL 全文索引和 LIKE 子句直接搜索你的现有数据库。对于许多应用程序，这是添加搜索功能最简单、最实用的方式——无需外部服务或额外的基础设施。

要使用 database 引擎，请将 SCOUT_DRIVER 环境变量设置为 database：

ini
SCOUT_DRIVER=database

配置完成后，你可以定义可搜索数据并开始对模型执行搜索查询。与第三方引擎不同，database 引擎不需要单独的索引步骤——它直接搜索你的数据库表。

自定义数据库搜索策略 ​

默认情况下，database 引擎会对你配置为可搜索的每个模型属性执行 LIKE 查询。但是，你可以为特定列分配更高效的搜索策略。SearchUsingFullText 属性将使用数据库的全文索引来搜索该列，而 SearchUsingPrefix 将只匹配字符串的开头（example%）而不是在整个字符串中搜索（%example%）。

要定义此行为，请将 PHP 属性分配给模型的 toSearchableArray 方法。没有属性的列将继续使用默认的 LIKE 策略：

php
use Laravel\Scout\Attributes\SearchUsingFullText;
use Laravel\Scout\Attributes\SearchUsingPrefix;

/**
 * 获取模型的可索引数据数组。
 *
 * @return array<string, mixed>
 */
#[SearchUsingPrefix(['id', 'email'])]
#[SearchUsingFullText(['bio'])]
public function toSearchableArray(): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        'bio' => $this->bio,
    ];
}

WARNING

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

Collection 引擎 ​

「collection」引擎适用于快速原型开发、极小的数据集（几百条记录）或运行测试。它从数据库中检索所有可能的记录，并使用 Laravel 的 Str::is 辅助函数在 PHP 中过滤它们，因此不需要任何索引或数据库特定的功能。对于超出简单用例的任何情况，你应该使用 database 引擎。

要使用 collection 引擎，你只需将 SCOUT_DRIVER 环境变量的值设置为 collection，或在应用程序的 scout 配置文件中直接指定 collection 驱动：

ini
SCOUT_DRIVER=collection

将 collection 驱动指定为首选驱动后，你可以开始对模型执行搜索查询。使用 collection 引擎时，不需要搜索引擎索引，例如为 Algolia、Meilisearch 或 Typesense 索引播种所需的索引。

与 Database 引擎的区别 ​

database 引擎使用全文索引和 LIKE 子句来高效查找匹配记录，而 collection 引擎会拉取所有记录并在 PHP 中过滤它们。collection 引擎是最具可移植性的选项，因为它可以在 Laravel 支持的所有关系数据库（包括 SQLite 和 SQL Server）上工作；但是，它的效率明显低于 database 引擎，不应与大型数据集一起使用。

第三方引擎配置 ​

以下配置选项仅在使用第三方搜索引擎（如 Algolia、Meilisearch 或 Typesense）时相关。如果你使用的是 database 引擎，可以跳过本节。

配置模型索引 ​

使用第三方引擎时，每个 Eloquent 模型都与一个给定的搜索「索引」同步，该索引包含该模型的所有可搜索记录。默认情况下，每个模型将被持久化到与模型的典型「表」名匹配的索引。通常，这是模型名称的复数形式；但是，你可以通过覆盖模型上的 searchableAs 方法来自定义模型的索引：

php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;

class Post extends Model
{
    use Searchable;

    /**
     * 获取与模型关联的索引名称。
     */
    public function searchableAs(): string
    {
        return 'posts_index';
    }
}

NOTE

searchableAs 方法在使用 database 引擎时无效，因为它始终直接搜索模型的数据库表。

配置模型 ID ​

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

php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;

class User extends Model
{
    use Searchable;

    /**
     * 获取用于索引模型的值。
     */
    public function getScoutKey(): mixed
    {
        return $this->email;
    }

    /**
     * 获取用于索引模型的键名。
     */
    public function getScoutKeyName(): mixed
    {
        return 'email';
    }
}

NOTE

getScoutKey 和 getScoutKeyName 方法在使用 database 引擎时无效，因为它始终使用模型的主键。

Algolia ​

索引设置 ​

有时你可能想在 Algolia 索引上配置额外的设置。虽然你可以通过 Algolia UI 管理这些设置，但有时直接从应用程序的 config/scout.php 配置文件管理索引配置的期望状态更高效。

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

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

php
use App\Models\User;
use App\Models\Flight;

'algolia' => [
    'id' => env('ALGOLIA_APP_ID', ''),
    'secret' => env('ALGOLIA_SECRET', ''),
    'index-settings' => [
        User::class => [
            'searchableAttributes' => ['id', 'name', 'email'],
            'attributesForFaceting'=> ['filterOnly(email)'],
            // 其他设置字段...
        ],
        Flight::class => [
            'searchableAttributes'=> ['id', 'destination'],
        ],
    ],
],

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

php
'index-settings' => [
    Flight::class => []
],

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

shell
php artisan scout:sync-index-settings

识别用户 ​

Scout 允许你在使用 Algolia 时自动识别用户。将已认证用户与搜索操作关联在查看 Algolia 仪表盘中的搜索分析时可能会有所帮助。你可以通过在应用程序的 .env 文件中将 SCOUT_IDENTIFY 环境变量定义为 true 来启用用户识别：

ini
SCOUT_IDENTIFY=true

启用此功能还会将请求的 IP 地址和已认证用户的主标识符传递给 Algolia，以便将此数据与用户发出的任何搜索请求关联。

Meilisearch ​

索引设置 ​

Meilisearch 要求你预定义索引搜索设置，例如可过滤属性、可排序属性和其他支持的设置字段。

可过滤属性是你计划在调用 Scout 的 where 方法时过滤的任何属性，而可排序属性是你计划在调用 Scout 的 orderBy 方法时排序的任何属性。要定义索引设置，请调整应用程序 scout 配置文件中 meilisearch 配置条目的 index-settings 部分：

php
use App\Models\User;
use App\Models\Flight;

'meilisearch' => [
    'host' => env('MEILISEARCH_HOST', 'http://localhost:7700'),
    'key' => env('MEILISEARCH_KEY', null),
    'index-settings' => [
        User::class => [
            'filterableAttributes'=> ['id', 'name', 'email'],
            'sortableAttributes' => ['created_at'],
            // 其他设置字段...
        ],
        Flight::class => [
            'filterableAttributes'=> ['id', 'destination'],
            'sortableAttributes' => ['updated_at'],
        ],
    ],
],

如果给定索引的底层模型是可软删除的并且包含在 index-settings 数组中，Scout 将自动在该索引上包含对软删除模型的过滤支持。如果你没有其他可过滤或可排序属性需要为可软删除模型索引定义，你可以简单地为该模型在 index-settings 数组中添加一个空条目：

php
'index-settings' => [
    Flight::class => []
],

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

shell
php artisan scout:sync-index-settings

可搜索数据类型 ​

Meilisearch 只会对正确类型的数据执行过滤操作（>、< 等）。自定义可搜索数据时，你应该确保数值被转换为正确的类型：

php
public function toSearchableArray()
{
    return [
        'id' => (int) $this->id,
        'name' => $this->name,
        'price' => (float) $this->price,
    ];
}

Typesense ​

准备可搜索数据 ​

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

php
/**
 * 获取模型的可索引数据数组。
 *
 * @return array<string, mixed>
 */
public function toSearchableArray(): array
{
    return array_merge($this->toArray(),[
        'id' => (string) $this->id,
        'created_at' => $this->created_at->timestamp,
    ]);
}

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

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

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

php
User::class => [
    'collection-schema' => [
        'fields' => [
            // ...
            [
                'name' => '__soft_deleted',
                'type' => 'int32',
                'optional' => true,
            ],
        ],
    ],
],

动态搜索参数 ​

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

php
use App\Models\Todo;

Todo::search('Groceries')->options([
    'query_by' => 'title, description'
])->get();

第三方引擎索引 ​

NOTE

本节描述的索引功能主要与使用第三方引擎（Algolia、Meilisearch 或 Typesense）相关。database 引擎直接搜索你的数据库表，因此不需要手动索引管理。

批量导入 ​

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

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

scout:queue-import 命令可用于使用队列任务导入所有现有记录：

shell
php artisan scout:queue-import "App\Models\Post" --chunk=500

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

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

修改导入查询 ​

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

php
use Illuminate\Database\Eloquent\Builder;

/**
 * 修改用于在使所有模型可搜索时检索模型的查询。
 */
protected function makeAllSearchableUsing(Builder $query): Builder
{
    return $query->with('author');
}

WARNING

使用队列批量导入模型时，makeAllSearchableUsing 方法可能不适用。当模型集合由任务处理时，关联不会被恢复。

添加记录 ​

将 Laravel\Scout\Searchable trait 添加到模型后，你只需 save 或 create 模型实例，它就会自动添加到搜索索引中。如果你已将 Scout 配置为使用队列，此操作将由你的队列 worker 在后台执行：

php
use App\Models\Order;

$order = new Order;

// ...

$order->save();

通过查询添加记录 ​

如果你想通过 Eloquent 查询将模型集合添加到搜索索引中，你可以将 searchable 方法链接到 Eloquent 查询上。searchable 方法将分块查询结果并将记录添加到搜索索引中。同样，如果你已将 Scout 配置为使用队列，所有分块将由队列 worker 在后台导入：

php
use App\Models\Order;

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

你也可以在 Eloquent 关联实例上调用 searchable 方法：

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

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

php
$orders->searchable();

NOTE

searchable 方法可以被视为一个「upsert」操作。换句话说，如果模型记录已经在你的索引中，它将被更新。如果它不存在于搜索索引中，它将被添加到索引中。

更新记录 ​

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

php
use App\Models\Order;

$order = Order::find(1);

// 更新订单...

$order->save();

你还可以在 Eloquent 查询实例上调用 searchable 方法来更新模型集合。如果模型不存在于搜索索引中，它们将被创建：

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

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

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

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

php
$orders->searchable();

导入前修改记录 ​

有时你可能需要在模型变为可搜索之前准备模型集合。例如，你可能想预加载一个关联，以便关联数据可以高效地添加到搜索索引中。要实现此目的，请在相应模型上定义一个 makeSearchableUsing 方法：

php
use Illuminate\Database\Eloquent\Collection;

/**
 * 修改正在变为可搜索的模型集合。
 */
public function makeSearchableUsing(Collection $models): Collection
{
    return $models->load('author');
}

有条件地更新搜索索引 ​

默认情况下，Scout 将重新索引更新的模型，无论修改了哪些属性。如果你想自定义此行为，你可以在模型上定义一个 searchIndexShouldBeUpdated 方法：

php
/**
 * 确定是否应更新搜索索引。
 */
public function searchIndexShouldBeUpdated(): bool
{
    return $this->wasRecentlyCreated || $this->wasChanged(['title', 'body']);
}

删除记录 ​

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

php
use App\Models\Order;

$order = Order::find(1);

$order->delete();

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

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

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

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

或者，如果内存中已经有一组 Eloquent 模型，你可以在集合实例上调用 unsearchable 方法从对应索引中删除模型实例：

php
$orders->unsearchable();

要从对应索引中删除所有模型记录，你可以调用 removeAllFromSearch 方法：

php
Order::removeAllFromSearch();

暂停索引 ​

有时你可能需要在不将模型数据同步到搜索索引的情况下对模型执行一批 Eloquent 操作。你可以使用 withoutSyncingToSearch 方法来实现。此方法接受一个会立即执行的闭包。闭包中发生的任何模型操作都不会同步到模型的索引：

php
use App\Models\Order;

Order::withoutSyncingToSearch(function () {
    // 执行模型操作...
});

有条件地可搜索的模型实例 ​

有时你可能需要仅在某些条件下使模型可搜索。例如，假设你有一个 App\Models\Post 模型，它可能处于两种状态之一：「draft」和「published」。你可能只希望「published」状态的帖子可搜索。要实现此目的，你可以在模型上定义一个 shouldBeSearchable 方法：

php
/**
 * 确定模型是否应该可搜索。
 */
public function shouldBeSearchable(): bool
{
    return $this->isPublished();
}

shouldBeSearchable 方法仅在通过 save 和 create 方法、查询或关联操作模型时应用。直接使用 searchable 方法使模型或集合可搜索将覆盖 shouldBeSearchable 方法的结果。

WARNING

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

搜索 ​

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

php
use App\Models\Order;

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

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

php
use App\Models\Order;
use Illuminate\Http\Request;

Route::get('/search', function (Request $request) {
    return Order::search($request->search)->get();
});

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

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

自定义索引 ​

使用第三方引擎搜索时，搜索查询通常会在模型的 searchableAs 方法指定的索引上执行。但是，你可以使用 within 方法指定应搜索的自定义索引：

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

Where 子句 ​

Scout 允许你向搜索查询添加简单的「where」子句。目前，这些子句仅支持基本的相等性检查，主要用于按所有者 ID 限定搜索查询范围：

php
use App\Models\Order;

$orders = Order::search('Star Trek')->where('user_id', 1)->get();

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

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

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

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

WARNING

如果你的应用程序使用 Meilisearch，你必须在使用 Scout 的「where」子句之前配置应用程序的可过滤属性。

自定义 Eloquent 结果查询 ​

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

php
use App\Models\Order;
use Illuminate\Database\Eloquent\Builder;

$orders = Order::search('Star Trek')
    ->query(fn (Builder $query) => $query->with('invoices'))
    ->get();

使用第三方引擎时，此回调在相关模型已从搜索引擎检索之后调用，因此不应用于「过滤」结果——请改用 Scout where 子句。但是，使用 database 引擎时，query 方法的约束会直接应用于数据库查询，因此你也可以将其用于过滤。

分页 ​

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

php
use App\Models\Order;

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

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

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

使用 database 引擎时，你还可以使用 simplePaginate 方法。与 paginate 不同的是，paginate 会检索匹配记录的总数以便显示页码，而 simplePaginate 仅确定当前页面之后是否有更多结果——对于只需要「上一页」和「下一页」链接的大型数据集来说更高效：

php
$orders = Order::search('Star Trek')->simplePaginate(15);

检索到结果后，你可以使用 Blade 显示结果和渲染分页链接，就像对传统 Eloquent 查询进行分页一样：

html
<div class="container">
    @foreach ($orders as $order)
        {{ $order->price }}
    @endforeach
</div>

{{ $orders->links() }}

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

php
use App\Models\Order;
use Illuminate\Http\Request;

Route::get('/orders', function (Request $request) {
    return Order::search($request->input('query'))->paginate(15);
});

WARNING

由于搜索引擎不知道你的 Eloquent 模型的全局作用域定义，你不应该在使用 Scout 分页的应用程序中使用全局作用域。或者，你应该在通过 Scout 搜索时重新创建全局作用域的约束。

软删除 ​

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

php
'soft_delete' => true,

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

php
use App\Models\Order;

// 检索结果时包含已删除的记录...
$orders = Order::search('Star Trek')->withTrashed()->get();

// 检索结果时仅包含已删除的记录...
$orders = Order::search('Star Trek')->onlyTrashed()->get();

NOTE

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

自定义引擎搜索 ​

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

php
use Algolia\AlgoliaSearch\SearchIndex;
use App\Models\Order;

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 抽象类。此抽象类包含你的自定义引擎必须实现的八个方法：

php
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。Scout 的引擎管理器可以从 Laravel 服务容器中解析。你应该从 App\Providers\AppServiceProvider 类或应用程序使用的任何其他服务提供者的 boot 方法中调用 extend 方法：

php
use App\ScoutExtensions\MySqlSearchEngine;
use Laravel\Scout\EngineManager;

/**
 * 引导任何应用程序服务。
 */
public function boot(): void
{
    resolve(EngineManager::class)->extend('mysql', function () {
        return new MySqlSearchEngine;
    });
}

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

php
'driver' => 'mysql',