后盾人

Appearance

Laravel Scout ​

简介 ​

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

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

安装 ​

首先，通过 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;
    }

队列 ​

虽然不是使用 Scout 的必要条件，但你应该强烈考虑在使用该库之前配置 队列驱动程序。运行队列工作进程将允许 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 作业使用的连接和队列，你应该运行一个队列工作进程来处理该连接和队列上的作业:

php
    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。

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

shell
composer require typesense/typesense-php

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

php
SCOUT_DRIVER=typesense
TYPESENSE_API_KEY=masterKey
TYPESENSE_HOST=localhost

如果需要，你还可以指定你的安装的端口、路径和协议:

php
TYPESENSE_PORT=8108
TYPESENSE_PATH=
TYPESENSE_PROTOCOL=http

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

为 Typesense 准备数据存储 ​

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

php
/**
 * 获取模型的可索引数据数组。
 *
 * @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 字段:

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

配置 ​

配置模型索引 ​

每个 Eloquent 模型都与给定的搜索"索引"同步，该索引包含该模型的所有可搜索记录。换句话说，你可以将每个索引视为 MySQL 表。默认情况下，每个模型将被持久化到与模型的典型"表"名称匹配的索引中。通常，这是模型名称的复数形式；但是，你可以通过在模型上重写 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';
        }
    }

配置可搜索数据 ​

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

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

php
    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 部分:

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

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

为每个模型配置搜索引擎 ​

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

php
    <?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;

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

识别用户 ​

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

ini
SCOUT_IDENTIFY=true

启用此功能还将传递请求的 IP 地址和你的经过身份验证的用户的主标识符给 Algolia，以便将这些数据与用户发出的任何搜索请求关联起来。

数据库/集合引擎 ​

数据库引擎 ​

WARNING

数据库引擎当前支持 MySQL 和 PostgreSQL。

如果你的应用程序与小到中型数据库交互或工作负载轻，你可能会发现使用 Scout 的"数据库"引擎更方便。数据库引擎将使用"where like"子句和全文索引从你现有的数据库中过滤结果，以确定查询的适用搜索结果。

要使用数据库引擎，你可以简单地将 SCOUT_DRIVER 环境变量的值设置为 database，或直接在应用程序的 scout 配置文件中指定 database 驱动程序:

ini
SCOUT_DRIVER=database

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

自定义数据库搜索策略 ​

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

要定义此行为，你可以为模型的 toSearchableArray 方法分配 PHP 属性。任何未分配额外搜索策略行为的列将继续使用默认的"where 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

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

集合引擎 ​

虽然你可以在本地开发过程中使用 Algolia、Meilisearch 或 Typesense 搜索引擎，但你可能会发现使用"集合"引擎更方便。集合引擎将使用"where"子句和现有数据库中的集合过滤来确定查询的适用搜索结果。使用此引擎时，不需要"索引"你的可搜索模型，因为它们将直接从你的本地数据库中检索。

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

ini
SCOUT_DRIVER=collection

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

与数据库引擎的差异 ​

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

集合引擎是最便携的搜索引擎，因为它可以跨所有 Laravel 支持的关系数据库（包括 SQLite 和 SQL Server）运行；但是，它比 Scout 的数据库引擎效率低。

索引 ​

批量导入 ​

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

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

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 方法可以被视为"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');
    }

删除记录 ​

要从索引中删除记录，你只需从数据库中 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 方法开始搜索模型。搜索方法接受一个单一的字符串，该字符串将用于搜索你的模型。然后，你应该将 get 方法链接到搜索查询上，以检索与给定搜索查询匹配的 Eloquent 模型:

php
    use App\Models\Order;

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

由于搜索结果返回一组 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();

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

WARNING

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

分页 ​

除了检索一组模型外，你还可以使用 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);

一旦你检索到结果，你可以显示结果并使用 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:

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

自定义 Eloquent Results 查询 ​

在 Scout 从应用程序的搜索引擎检索到匹配的 Eloquent 模型列表后，Eloquent 用于按主键检索所有匹配的模型。您可以通过调用 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();

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

自定义引擎 ​

编写引擎 ​

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

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;

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

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

'driver' => 'mysql',

后盾人版权所有 © 2018-2025 创作不易请尊重他人劳动成果，未经授权禁止转载！