Laravel Scout

简介
安装
- 队列
驱动前提条件
配置
- 配置可搜索数据
数据库/集合引擎
- 数据库引擎
- 集合引擎
第三方引擎配置
第三方引擎索引
搜索
自定义引擎

简介

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

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

当你需要大规模容错、分面过滤或地理搜索等功能时，Scout 还包括用于 Algolia、Meilisearch 和 Typesense 的驱动程序。此外，还有一个用于本地开发的“集合”驱动，你也可以自由编写自定义引擎。

安装

首先，通过 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/meilisearch-php 版本与你的 Meilisearch 二进制版本兼容。

WARNING

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

Typesense

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

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

要开始使用 Scout 与 Typesense，请通过 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 集合的其他设置和架构定义可以在应用程序的 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');
    }
}

数据库/集合引擎

数据库引擎

WARNING

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

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

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

ini

SCOUT_DRIVER=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

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

集合引擎

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

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

ini

SCOUT_DRIVER=collection

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

与数据库引擎的区别

数据库引擎使用全文索引和 LIKE 子句高效地查找匹配记录，而集合引擎则提取所有记录并在 PHP 中过滤它们。集合引擎是最便携的选项，因为它可以在 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';
    }
}

NOTE

使用数据库引擎时，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';
    }
}

NOTE

使用数据库引擎时，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();

第三方引擎索引

NOTE

本节中描述的索引功能主要在使用第三方引擎（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

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 配置为使用队列，此操作将由你的队列工作器在后台执行：

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();

NOTE

searchable 方法可以被视为“更新或插入”操作。换句话说，如果模型记录已存在于你的索引中，它将被更新。如果它不存在于搜索索引中，它将被添加到索引中。

更新记录

要更新一个可搜索模型，你只需要更新模型实例的属性并将模型 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 方法的结果。

WARNING

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

你也可以使用 =、!=、<、>、>=、<= 比较运算符来构建更高级的查询：

php

Order::search('Star Trek')
  ->where('status', '=', 'completed')
  ->where('is_refunded', '!=', true)
  ->where('total_price', '>', 100)
  ->where('shipping_cost', '<', 20)
  ->where('discount_percent', '>=', 10)
  ->where('item_count', '<=', 5)
  ->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 子句。但是，当使用数据库引擎时，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);

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

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',

Laravel Scout ​

简介 ​

安装 ​

队列 ​

驱动前提条件 ​

Algolia ​

Meilisearch ​

Typesense ​

配置 ​

配置可搜索数据 ​

配置模型引擎 ​

数据库/集合引擎 ​

数据库引擎 ​

自定义数据库搜索策略 ​

集合引擎 ​

与数据库引擎的区别 ​

第三方引擎配置 ​

配置模型索引 ​

配置模型 ID ​

Algolia ​

索引设置 ​

标识用户 ​

Meilisearch ​

索引设置 ​

可搜索数据类型 ​

Typesense ​

准备可搜索数据 ​

动态搜索参数 ​

第三方引擎索引 ​

批量导入 ​

修改导入查询 ​

添加记录 ​

通过查询添加记录 ​

更新记录 ​

在导入前修改记录 ​

有条件地更新搜索索引 ​

删除记录 ​

暂停索引 ​

条件性可搜索模型实例 ​

搜索 ​

自定义索引 ​

Where 子句 ​

自定义 Eloquent 结果查询 ​

分页 ​

软删除 ​

自定义引擎搜索 ​

自定义引擎 ​

编写引擎 ​

注册引擎 ​

Laravel Scout

简介

安装

队列

驱动前提条件

Algolia

Meilisearch

Typesense

配置

配置可搜索数据

配置模型引擎

数据库/集合引擎

数据库引擎

自定义数据库搜索策略

集合引擎

与数据库引擎的区别

第三方引擎配置

配置模型索引

配置模型 ID

Algolia

索引设置

标识用户

Meilisearch

索引设置

可搜索数据类型

Typesense

准备可搜索数据

动态搜索参数

第三方引擎索引

批量导入

修改导入查询

添加记录

通过查询添加记录

更新记录

在导入前修改记录

有条件地更新搜索索引

删除记录

暂停索引

条件性可搜索模型实例

搜索

自定义索引

Where 子句

自定义 Eloquent 结果查询

分页

软删除

自定义引擎搜索

自定义引擎

编写引擎

注册引擎