Laravel Scout

介绍
安装
- 驱动程序先决条件
- 队列
配置
本地开发
索引
搜索
自定义引擎
构建器宏

介绍

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

目前，Scout 附带 Algolia 和 MeiliSearch 驱动程序。此外，Scout 包含一个“集合”驱动程序，专为本地开发使用而设计，不需要任何外部依赖项或第三方服务。此外，编写自定义驱动程序很简单，您可以自由扩展 Scout 以实现自己的搜索实现。

安装

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

php

composer require laravel/scout

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

php

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;
}

驱动程序先决条件

Algolia

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

php

composer require algolia/algoliasearch-client-php

MeiliSearch

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

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

php

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

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

php

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

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

此外，您应确保安装的 meilisearch/meilisearch-php 版本与您的 MeiliSearch 二进制版本兼容，具体请查阅 MeiliSearch 的二进制兼容性文档。

NOTE

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

队列

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

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

php

'queue' => true,

配置

配置模型索引

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

php

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;

class Post extends Model
{
    use Searchable;

    /**
     * 获取与模型关联的索引的名称。
     *
     * @return string
     */
    public function searchableAs()
    {
        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
     */
    public function toSearchableArray()
    {
        $array = $this->toArray();

        // 自定义数据数组...

        return $array;
    }
}

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

    /**
     * 获取用于索引模型的值。
     *
     * @return mixed
     */
    public function getScoutKey()
    {
        return $this->email;
    }

    /**
     * 获取用于索引模型的键名。
     *
     * @return mixed
     */
    public function getScoutKeyName()
    {
        return 'email';
    }
}

识别用户

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

php

SCOUT_IDENTIFY=true

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

本地开发

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

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

ini

SCOUT_DRIVER=collection

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

索引

批量导入

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

php

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

flush 命令可用于从搜索索引中删除模型的所有记录：

php

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

修改导入查询

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

php

/**
 * 修改用于在使所有模型可搜索时检索模型的查询。
 *
 * @param  \Illuminate\Database\Eloquent\Builder  $query
 * @return \Illuminate\Database\Eloquent\Builder
 */
protected function makeAllSearchableUsing($query)
{
    return $query->with('author');
}

添加记录

一旦将 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();

删除记录

要从索引中删除记录，您可以简单地从数据库中 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();

暂停索引

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

php

use App\Models\Order;

Order::withoutSyncingToSearch(function () {
    // 执行模型操作...
});

有条件的可搜索模型实例

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

php

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

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

搜索

您可以使用 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', ['paid', 'open']
)->get();

由于搜索索引不是关系数据库，因此目前不支持更高级的“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);
});

软删除

如果您的索引模型是软删除的，并且您需要搜索软删除的模型，请将 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 中。可以从 Laravel 服务容器中解析 Scout 的引擎管理器。您应该从 App\Providers\AppServiceProvider 类的 boot 方法或应用程序使用的任何其他服务提供程序中调用 extend 方法：

php

use App\ScoutExtensions\MySqlSearchEngine
use Laravel\Scout\EngineManager;

/**
 * 启动任何应用程序服务。
 *
 * @return void
 */
public function boot()
{
    resolve(EngineManager::class)->extend('mysql', function () {
        return new MySqlSearchEngine;
    });
}

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

php

'driver' => 'mysql',

构建器宏

如果您想定义自定义的 Scout 搜索构建器方法，可以在 Laravel\Scout\Builder 类上使用 macro 方法。通常，“宏”应在服务提供程序的 boot 方法中定义：

php

use Illuminate\Support\Facades\Response;
use Illuminate\Support\ServiceProvider;
use Laravel\Scout\Builder;

/**
 * 启动任何应用程序服务。
 *
 * @return void
 */
public function boot()
{
    Builder::macro('count', function () {
        return $this->engine()->getTotalCount(
            $this->engine()->search($this)
        );
    });
}

macro 函数接受宏名称作为第一个参数，闭包作为第二个参数。当从 Laravel\Scout\Builder 实现中调用宏名称时，将执行宏的闭包：

php

use App\Models\Order;

Order::search('Star Trek')->count();

Laravel Scout ​

介绍 ​

安装 ​

驱动程序先决条件 ​

Algolia ​

MeiliSearch ​

队列 ​

配置 ​

配置模型索引 ​

配置可搜索数据 ​

配置模型 ID ​

识别用户 ​

本地开发 ​

索引 ​

批量导入 ​

修改导入查询 ​

添加记录 ​

通过查询添加记录 ​

更新记录 ​

删除记录 ​

暂停索引 ​

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

搜索 ​

自定义索引 ​

Where 子句 ​

分页 ​

软删除 ​

自定义引擎搜索 ​

自定义引擎 ​

编写引擎 ​

注册引擎 ​

构建器宏 ​

Laravel Scout

介绍

安装

驱动程序先决条件

Algolia

MeiliSearch

队列

配置

配置模型索引

配置可搜索数据

配置模型 ID

识别用户

本地开发

索引

批量导入

修改导入查询

添加记录

通过查询添加记录

更新记录

删除记录

暂停索引

有条件的可搜索模型实例

搜索

自定义索引

Where 子句

分页

软删除

自定义引擎搜索

自定义引擎

编写引擎

注册引擎

构建器宏