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 引擎时，在使用该库之前，您应认真考虑配置一个队列驱动。运行队列工作进程将允许 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 作业使用的连接和队列，则应运行队列工作程序以处理该连接和队列上的作业：

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-php 版本与您的 Meilisearch 二进制版本兼容，具体请查阅 Meilisearch 的二进制兼容性文档。

警告

在使用 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 的更多信息，请查阅 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');
    }
}

数据库/集合引擎

数据库引擎

警告

数据库引擎目前支持 MySQL 和 PostgreSQL，两者都支持快速的全文列索引。

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

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

ini

SCOUT_DRIVER=database

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

自定义数据库搜索策略

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

要定义此行为，请为模型的 toSearchableArray 方法分配 PHP 属性。任何没有属性的列将继续使用默认的 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,
    ];
}

警告

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

集合引擎

"collection" 引擎适用于快速原型、极小数据集（几百条记录）或运行测试。它会从数据库中检索所有可能的记录，并使用 Laravel 的 Str::is 辅助函数在 PHP 中进行筛选，因此不需要任何索引或数据库特定功能。对于任何超出简单用例的场景，您应改用数据库引擎。

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

ini

SCOUT_DRIVER=collection

一旦您将 collection 驱动指定为首选驱动，就可以开始对模型执行搜索查询。使用 collection 引擎时，无需进行搜索引擎索引操作（例如为填充 Algolia、Meilisearch 或 Typesense 索引所需的索引操作）。

与数据库引擎的区别

虽然数据库引擎使用全文索引和 LIKE 子句高效查找匹配记录，但 collection 引擎会拉取所有记录并在 PHP 中进行筛选。collection 引擎是可移植性最佳的选择，因为它适用于 Laravel 支持的所有关系数据库（包括 SQLite 和 SQL Server）；然而，它的效率远低于数据库引擎，不应用于大型数据集。

第三方引擎配置

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

配置模型索引

当使用第三方引擎时，每个 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';
    }
}

注意

当使用数据库引擎时，searchableAs 方法没有效果，该引擎总是直接搜索模型的数据库表。

配置模型 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';
    }
}

注意

当使用数据库引擎时，getScoutKey 和 getScoutKeyName 方法没有效果，该引擎总是使用模型的主键。

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 集合架构。集合架构描述了可通过 Typesense 搜索的每个字段的数据类型。有关所有可用架构选项的更多信息，请查阅 Typesense 文档。

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

如果你的可搜索模型支持软删除，你应在应用程序的 config/scout.php 配置文件中，于模型对应的 Typesense 架构中定义一个 __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();

第三方引擎索引

注意

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

批量导入

如果您正在现有项目中安装 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

scout:queue 命令可用于通过队列任务导入你所有的已有记录：

shell

php artisan scout:queue "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');
}

警告

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

添加记录

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

php

use App\Models\Order;

$order = new Order;

// ...

$order->save();

通过查询添加记录

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

php

use App\Models\Order;

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

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

php

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

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

php

$orders->searchable();

注意

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 模型，该模型可能处于两种状态之一：“草稿”和“已发布”。您可能只希望允许“已发布”的帖子可搜索。为此，您可以在模型上定义一个 shouldBeSearchable 方法：

php

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

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

警告

shouldBeSearchable 方法不适用于使用 Scout 的“数据库”引擎，因为所有可搜索数据始终存储在数据库中。要在使用数据库引擎时实现类似行为，您应使用 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();

警告

如果你的应用程序使用的是 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 子句。然而，当使用数据库引擎时，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);

当使用数据库引擎时，你也可以使用 simplePaginate 方法。与 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);
});

警告

由于搜索引擎不了解 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();

注意

当使用 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 中。可以从 Laravel 服务容器中解析 Scout 的引擎管理器。您应该从应用程序的 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',

Laravel Scout ​

介绍 ​

安装 ​

队列 ​

驱动程序先决条件 ​

Algolia ​

Meilisearch ​

Typesense ​

配置 ​

配置可搜索数据 ​

配置模型搜索引擎 ​

数据库/集合引擎 ​

数据库引擎 ​

自定义数据库搜索策略 ​

集合引擎 ​

与数据库引擎的区别 ​

第三方引擎配置 ​

配置模型索引 ​

配置模型 ID ​

Algolia ​

索引设置 ​

识别用户 ​

Meilisearch ​

索引设置 ​

可搜索数据类型 ​

Typesense ​

准备可搜索数据 ​

动态搜索参数 ​

第三方引擎索引 ​

批量导入 ​

修改导入查询 ​

添加记录 ​

通过查询添加记录 ​

更新记录 ​

在导入之前修改记录 ​

条件性更新搜索索引 ​

删除记录 ​

暂停索引 ​

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

搜索 ​

自定义索引 ​

Where 子句 ​

自定义 Eloquent 结果查询 ​

分页 ​

软删除 ​

自定义引擎搜索 ​

自定义引擎 ​

编写引擎 ​

注册引擎 ​

Laravel Scout

介绍

安装

队列

驱动程序先决条件

Algolia

Meilisearch

Typesense

配置

配置可搜索数据

配置模型搜索引擎

数据库/集合引擎

数据库引擎

自定义数据库搜索策略

集合引擎

与数据库引擎的区别

第三方引擎配置

配置模型索引

配置模型 ID

Algolia

索引设置

识别用户

Meilisearch

索引设置

可搜索数据类型

Typesense

准备可搜索数据

动态搜索参数

第三方引擎索引

批量导入

修改导入查询

添加记录

通过查询添加记录

更新记录

在导入之前修改记录

条件性更新搜索索引

删除记录

暂停索引

有条件的可搜索模型实例

搜索

自定义索引

Where 子句

自定义 Eloquent 结果查询

分页

软删除

自定义引擎搜索

自定义引擎

编写引擎

注册引擎