跳转至内容

Laravel Scout

简介

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

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

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

安装

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

1composer require laravel/scout

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

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

最后，将 Laravel\Scout\Searchable trait 添加到您想要搜索的模型中。该 trait 将注册一个模型观察者，自动保持模型与您的搜索驱动同步：

 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}

队列化

当使用非 database 或 collection 引擎时，您应该强烈考虑在配置库之前先配置一个 队列驱动程序。运行队列处理器可以使 Scout 将同步模型信息到搜索索引的所有操作放入队列，从而为您的应用程序 Web 界面提供更好的响应速度。

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

1'queue' => true,

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

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

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

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

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

驱动前提条件

Algolia

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

1composer require algolia/algoliasearch-client-php

Meilisearch

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

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

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

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

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

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

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

在升级使用 Meilisearch 的应用程序上的 Scout 时，应始终 查看 Meilisearch 服务本身的任何其他重大变更。

Typesense

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

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

要开始在 Scout 中使用 Typesense，请通过 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 文档。

配置

配置可搜索数据

默认情况下，给定模型的完整 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}

配置模型引擎

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

 1<?php
 2 
 3namespace App\Models;
 4 
 5use Illuminate\Database\Eloquent\Model;
 6use Laravel\Scout\Engines\Engine;
 7use Laravel\Scout\Scout;
 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 Scout::engine('meilisearch');
20    }
21}

数据库 / 集合引擎

数据库引擎

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

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

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

1SCOUT_DRIVER=database

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

自定义数据库搜索策略

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

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

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

集合引擎

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

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

1SCOUT_DRIVER=collection

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

与数据库引擎的区别

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

第三方引擎配置

以下配置选项仅在您使用 Algolia、Meilisearch 或 Typesense 等第三方搜索引擎时才相关。如果您使用的是 数据库引擎，则可以跳过此部分。

配置模型索引

使用第三方引擎时，每个 Eloquent 模型都会与一个给定的搜索“索引”同步，其中包含该模型的所有可搜索记录。默认情况下，每个模型都将持久化到与模型“表”名称匹配的索引中。通常，这是模型名称的复数形式；但是，您可以自由通过覆盖模型上的 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}

当使用数据库引擎时，searchableAs 方法无效，因为数据库引擎总是直接搜索模型的数据库表。

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

当使用数据库引擎时，getScoutKey 和 getScoutKeyName 方法无效，因为数据库引擎总是使用模型的主键。

Algolia

索引设置

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

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

首先，在应用程序的 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],

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

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

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

1php artisan scout:sync-index-settings

识别用户

Scout 允许您在使用 Algolia 时自动识别用户。将已认证用户与搜索操作关联起来，有助于在查看 Algolia 控制面板内的搜索分析时进行跟踪。您可以通过在应用程序的 .env 文件中定义 SCOUT_IDENTIFY 环境变量为 true 来启用用户识别：

1SCOUT_IDENTIFY=true

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

Meilisearch

索引设置

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

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

 1use App\Models\User;
 2use App\Models\Flight;
 3 
 4'meilisearch' => [
 5    'host' => env('MEILISEARCH_HOST', 'https://: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-settings Artisan 命令。此命令将通知 Meilisearch 您当前配置的索引设置。为了方便起见，您可能希望将此命令作为部署过程的一部分。

1php artisan scout:sync-index-settings

可搜索数据类型

Meilisearch 仅会对正确类型的数据执行过滤操作 (>, < 等)。在自定义可搜索数据时，应确保数值被转换为正确的类型。

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

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 修改集合模式而不删除任何索引数据。

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

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

第三方引擎索引

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

批量导入

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

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

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

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

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 trait 添加到模型中，您只需要 save 或 create 一个模型实例，它就会自动添加到您的搜索索引中。如果您已配置 Scout 使用队列，此操作将由您的队列处理器在后台执行：

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

通过查询添加记录

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

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

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

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

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

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}

有条件地更新搜索索引

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

1/**
2 * Determine if the search index should be updated.
3 */
4public function searchIndexShouldBeUpdated(): bool
5{
6    return $this->wasRecentlyCreated || $this->wasChanged(['title', 'body']);
7}

移除记录

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

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

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

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 方法的结果。

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

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

自定义 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();

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

分页

除了检索模型集合外，您还可以使用 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);

使用数据库引擎时，您也可以使用 simplePaginate 方法。与 paginate 不同（它会检索总记录数以便显示页码），simplePaginate 仅确定当前页面之外是否还有更多结果，这对于只需要“上一页”和“下一页”链接的大型数据集更有效：

1$orders = Order::search('Star Trek')->simplePaginate(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 搜索时重新创建全局作用域的约束。

软删除

如果您的索引模型正在进行 软删除 并且您需要搜索已软删除的模型，请将 config/scout.php 配置文件的 soft_delete 选项设置为 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();

自定义引擎

编写引擎

如果内置的 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 类对这些方法的实现可能会有所帮助。此类将为您学习如何在自己的引擎中实现这些方法提供一个良好的起点。

注册引擎

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

 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}

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

1'driver' => 'mysql',

Laravel 是构建、部署和监控软件
 最高效的方式。

产品

Packages

资源

合作伙伴