Laravel Scout

• 简介
• 安装
  • 排队
• 驱动程序先决条件
  • Algolia
  • Meilisearch
  • Typesense
• 配置
  • 配置模型索引
  • 配置可搜索数据
  • 配置模型 ID
  • 配置每个模型的搜索引擎
  • 识别用户
• 数据库/集合引擎
  • 数据库引擎
  • 集合引擎
• 索引
  • 批量导入
  • 添加记录
  • 更新记录
  • 删除记录
  • 暂停索引
  • 有条件可搜索的模型实例
• 搜索
  • Where 子句
  • 分页
  • 软删除
  • 自定义引擎搜索
• 自定义引擎

简介

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

目前，Scout 附带了 Algolia、Meilisearch、Typesense 和 MySQL/PostgreSQL (database) 驱动程序。此外，Scout 包含一个“collection”驱动程序，该驱动程序专为本地开发使用而设计，不需要任何外部依赖项或第三方服务。此外，编写自定义驱动程序很简单，你可以自由地使用自己的搜索实现扩展 Scout。

安装

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

composer require laravel/scout

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

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

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

<?php
 
namespace App\Models;
 
use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;
 
class Post extends Model
{
    use Searchable;
}

排队

虽然使用 Scout 不严格要求，但你应该在使用库之前认真考虑配置一个 队列驱动程序。运行一个队列工作者将允许 Scout 将所有将模型信息同步到你的搜索索引的操作排队，从而为你的应用程序的 Web 界面提供更好的响应时间。

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

'queue' => true,

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

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

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

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

php artisan queue:work redis --queue=scout

驱动程序先决条件

Algolia

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

composer require algolia/algoliasearch-client-php

Meilisearch

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

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

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

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

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

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

此外，你应该确保你安装的 meilisearch/meilisearch-php 版本与你的 Meilisearch 二进制版本兼容，方法是查看 Meilisearch 有关二进制兼容性的文档。

Typesense

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

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

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

composer require typesense/typesense-php

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

SCOUT_DRIVER=typesense
TYPESENSE_API_KEY=masterKey
TYPESENSE_HOST=localhost

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

TYPESENSE_PORT=8108
TYPESENSE_PATH=
TYPESENSE_PROTOCOL=http

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

准备用于存储在 Typesense 中的数据

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

/**
 * Get the indexable data array for the model.
 *
 * @return array<string, mixed>
 */
public function toSearchableArray()
{
    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 字段

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

动态搜索参数

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

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

配置

配置模型索引

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

<?php
 
namespace App\Models;
 
use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;
 
class Post extends Model
{
    use Searchable;
 
    /**
     * Get the name of the index associated with the model.
     */
    public function searchableAs(): string
    {
        return 'posts_index';
    }
}

配置可搜索数据

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

<?php
 
namespace App\Models;
 
use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;
 
class Post extends Model
{
    use Searchable;
 
    /**
     * Get the indexable data array for the model.
     *
     * @return array<string, mixed>
     */
    public function toSearchableArray(): array
    {
        $array = $this->toArray();
 
        // Customize the data array...
 
        return $array;
    }
}

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

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

配置可过滤数据和索引设置 (Meilisearch)

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

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

use App\Models\User;
use App\Models\Flight;
 
'meilisearch' => [
    'host' => env('MEILISEARCH_HOST', 'https://127.0.0.1:7700'),
    'key' => env('MEILISEARCH_KEY', null),
    'index-settings' => [
        User::class => [
            'filterableAttributes'=> ['id', 'name', 'email'],
            'sortableAttributes' => ['created_at'],
            // Other settings fields...
        ],
        Flight::class => [
            'filterableAttributes'=> ['id', 'destination'],
            'sortableAttributes' => ['updated_at'],
        ],
    ],
],

如果给定索引的基础模型是软删除的并且包含在 `index-settings` 数组中，Scout 将自动包含对该索引上的软删除模型进行过滤的支持。如果您没有其他可过滤或可排序属性需要为软删除模型索引定义，您只需在该模型的 `index-settings` 数组中添加一个空条目。

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

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

php artisan scout:sync-index-settings

配置模型 ID

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

<?php
 
namespace App\Models;
 
use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;
 
class User extends Model
{
    use Searchable;
 
    /**
     * Get the value used to index the model.
     */
    public function getScoutKey(): mixed
    {
        return $this->email;
    }
 
    /**
     * Get the key name used to index the model.
     */
    public function getScoutKeyName(): mixed
    {
        return 'email';
    }
}

配置每个模型的搜索引擎

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

<?php
 
namespace App\Models;
 
use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Engines\Engine;
use Laravel\Scout\EngineManager;
use Laravel\Scout\Searchable;
 
class User extends Model
{
    use Searchable;
 
    /**
     * Get the engine used to index the model.
     */
    public function searchableUsing(): Engine
    {
        return app(EngineManager::class)->engine('meilisearch');
    }
}

识别用户

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

SCOUT_IDENTIFY=true

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

数据库/集合引擎

数据库引擎

如果您的应用程序与中小型数据库交互或工作量很轻，您可能会发现从 Scout 的“数据库”引擎开始会更方便。数据库引擎将在从现有数据库中过滤结果时使用“where like”子句和全文索引，以确定您的查询适用的搜索结果。

要使用数据库引擎，您只需将 `SCOUT_DRIVER` 环境变量的值设置为 `database`，或者在应用程序的 `scout` 配置文件中直接指定 `database` 驱动程序。

SCOUT_DRIVER=database

指定数据库引擎作为首选驱动程序后，您必须 配置可搜索数据。然后，您可以开始对模型执行 搜索查询。在使用数据库引擎时，不需要搜索引擎索引，例如为 Algolia、Meilisearch 或 Typesense 索引播种所需的索引。

自定义数据库搜索策略

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

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

use Laravel\Scout\Attributes\SearchUsingFullText;
use Laravel\Scout\Attributes\SearchUsingPrefix;
 
/**
 * Get the indexable data array for the model.
 *
 * @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,
    ];
}

集合引擎

虽然您可以在本地开发期间自由使用 Algolia、Meilisearch 或 Typesense 搜索引擎，但您可能会发现从“集合”引擎开始会更方便。集合引擎将使用“where”子句和对来自现有数据库的结果进行集合过滤，以确定您的查询适用的搜索结果。在使用此引擎时，没有必要“索引”您的可搜索模型，因为它们将直接从本地数据库中检索。

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

SCOUT_DRIVER=collection

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

与数据库引擎的区别

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

集合引擎是最便携的搜索引擎，因为它适用于 Laravel 支持的所有关系数据库（包括 SQLite 和 SQL Server）；但是，它不如 Scout 的数据库引擎高效。

索引

批量导入

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

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

可以使用 `flush` 命令从搜索索引中删除模型的所有记录。

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

修改导入查询

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

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

添加记录

将 `Laravel\Scout\Searchable` 特性添加到模型后，您只需要 `save` 或 `create` 一个模型实例，它将自动添加到您的搜索索引中。如果您已将 Scout 配置为 使用队列，此操作将由您的队列工作者在后台执行。

use App\Models\Order;
 
$order = new Order;
 
// ...
 
$order->save();

通过查询添加记录

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

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

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

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

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

$orders->searchable();

更新记录

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

use App\Models\Order;
 
$order = Order::find(1);
 
// Update the order...
 
$order->save();

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

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

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

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

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

$orders->searchable();

在导入之前修改记录

有时您可能需要在模型变得可搜索之前准备模型集合。例如，您可能想要急切加载一个关系，以便关系数据可以有效地添加到您的搜索索引中。为此，请在相应的模型上定义一个 `makeSearchableUsing` 方法。

use Illuminate\Database\Eloquent\Collection;
 
/**
 * Modify the collection of models being made searchable.
 */
public function makeSearchableUsing(Collection $models): Collection
{
    return $models->load('author');
}

删除记录

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

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

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

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

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

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

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

$orders->unsearchable();

要从其对应的索引中删除所有模型记录，您可以在其上调用 `removeAllFromSearch` 方法。

Order::removeAllFromSearch();

暂停索引

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

use App\Models\Order;
 
Order::withoutSyncingToSearch(function () {
    // Perform model actions...
});

有条件可搜索的模型实例

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

/**
 * Determine if the model should be searchable.
 */
public function shouldBeSearchable(): bool
{
    return $this->isPublished();
}

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

搜索

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

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

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

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

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

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

自定义索引

搜索查询通常会在模型的 searchableAs 方法指定的索引上执行。但是，您可以使用 within 方法指定要搜索的自定义索引。

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

Where 子句

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

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

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

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

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

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

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

分页

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

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

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

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

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

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

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

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

软删除

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

'soft_delete' => true,

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

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

自定义引擎搜索

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

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

自定义 Eloquent 结果查询

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

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

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

自定义引擎

编写引擎

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

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 方法。

use App\ScoutExtensions\MySqlSearchEngine;
use Laravel\Scout\EngineManager;
 
/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    resolve(EngineManager::class)->extend('mysql', function () {
        return new MySqlSearchEngine;
    });
}

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

'driver' => 'mysql',