Skip to content

Laravel Scout

介绍

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

目前,Scout 附带 AlgoliaMeiliSearch 驱动程序。此外,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 的 idsecret 凭据。配置好凭据后,您还需要通过 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 的 hostkey 凭据:

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

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

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

exclamation

在使用 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 / 键。如果您需要自定义此行为,可以覆盖模型上的 getScoutKeygetScoutKeyName 方法:

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 添加到模型中,您只需 savecreate 一个模型实例,它就会自动添加到搜索索引中。如果您已配置 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();
lightbulb

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 方法仅在通过 savecreate 方法、查询或关系操作模型时应用。直接使用 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 属性。然后,您可以在搜索时使用 withTrashedonlyTrashed 方法来检索软删除的记录:

php
use App\Models\Order;

// 在检索结果时包括已删除的记录...
$orders = Order::search('Star Trek')->withTrashed()->get();

// 在检索结果时仅包括已删除的记录...
$orders = Order::search('Star Trek')->onlyTrashed()->get();
lightbulb

当使用 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();