Laravel Scout

• 简介
• 安装
  • 队列
  • 驱动前提
• 配置
  • 配置模型索引
  • 配置可搜索数据
  • 配置模型 ID
• 索引
  • 批量导入
  • 添加记录
  • 更新记录
  • 删除记录
  • 暂停索引
  • 有条件地让模型实例可搜索
• 搜索
  • Where 语句
  • 分页
  • 软删除
  • 自定义引擎搜索行为
• 自定义引擎
• 构造器宏

简介

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

目前，Scout 自带了 Algolia 驱动；当然，编写自定义驱动也很简单，您可以自由使用自己的搜索实现扩展 Scout。

安装

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

composer require laravel/scout

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

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

最后，将 Laravel\Scout\Searchable Trait 添加到想要搜索的模型。此 Trait 会注册一个模型观察者使模型与搜索驱动保持同步：

namespace App;

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

class Post extends Model
{
    use Searchable;
}

队列

尽管使用 Scout 时不严格要求，但在使用库之前还是应该强烈考虑配置 队列驱动。运行队列处理器将允许 Scout 在队列中处理将模型信息同步到搜索索引的所有操作，从而为应用的 Web 界面提供了更快的响应时间。

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

'queue' => true,

驱动前提

Algolia

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

composer require algolia/algoliasearch-client-php

配置

配置模型索引

每个模型都与给定的搜索「索引」同步，该索引包含模型的所有可搜索记录。换句话说，可以将每个索引视为 MySQL 表。默认情况下，每个模型都会被持久化到与模型的「表」名相匹配的索引。通常情况下，这是模型名的复数形式；不过，可以通过重写模型上的 searchableAs 方法自定义模型的索引：

namespace App;

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

class Post extends Model
{
    use Searchable;

    /**
     * 获取模型的索引名称
     *
     * @return string
     */
    public function searchableAs()
    {
        return 'posts_index';
    }
}

配置可搜索数据

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

namespace App;

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

class Post extends Model
{
    use Searchable;

    /**
     * 获取模型的可搜索数据
     *
     * @return array
     */
    public function toSearchableArray()
    {
        $array = $this->toArray();

        // 自定义数组

        return $array;
    }
}

配置模型 ID

默认情况下，Scout 会使用模型的主键作为唯一 ID 存储到搜索索引。如果需要自定义此行为，可以重写模型上的 getScoutKey 方法：

namespace App;

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

class User extends Model
{
    use Searchable;

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

索引

批量导入

如果将 Scout 安装到已有项目，可能已经有需要导入到搜索驱动的数据库记录了。Scout 提供的 Artisan 命令 import 可用于将所有已有记录导入到搜索索引：

php artisan scout:import "App\Post"

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

php artisan scout:flush "App\Post"

添加记录

添加 Laravel\Scout\Searchable Trait 到模型后，只需要 save 模型实例，模型就会自动被添加到搜索索引。如果为 Scout 配置了 使用队列，那么队列处理器会在后台执行此操作：

$order = new App\Order;

// ...

$order->save();

通过查询添加

如果要通过 Eloquent 查询将模型集合添加到搜索索引，可以在 Eloquent 查询上链式调用 searchable 方法。searchable 方法会将查询结果 分块 并将记录添加到搜索索引。同样，如果为 Scout 配置了使用队列，队列处理器会在后台添加所有分块：

// 通过 Eloquent 查询添加
App\Order::where('price', '>', 100)->searchable();

// 也可以通过关联添加记录
$user->orders()->searchable();

// 还可以通过集合添加记录
$orders->searchable();

searchable 方法可认为时一个「更新插入」操作。换句话说，如果模型记录在索引中已存在，那么会被更新。如果搜索索引中不存在，那么会将其添加到索引。

更新记录

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

$order = App\Order::find(1);

// 更新订单

$order->save();

也可以在 Eloquent 查询上使用 searchable 方法更新模型集合。如果模型在搜索索引中不存在，它们会被创建：

// 通过 Eloquent 查询更新
App\Order::where('price', '>', 100)->searchable();

// 也可以通过关联更新
$user->orders()->searchable();

// 还可以通过集合更新
$orders->searchable();

删除记录

要从索引中删除记录，可以从数据库中 delete 模型。这种删除形式甚至兼容 软删除 模型：

$order = App\Order::find(1);

$order->delete();

如果不想在删除记录前获取模型，可以在 Eloquent 查询实例或集合上使用 unsearchable 方法：

// 通过 Eloquent 查询删除
App\Order::where('price', '>', 100)->unsearchable();

// 也可以通过关联删除
$user->orders()->unsearchable();

// 还可以通过集合删除
$orders->unsearchable();

暂停索引

有时可能需要在模型上执行批量 Eloquent 操作，而不用将模型数据同步到搜索索引。可以使用 withoutSyncingToSearch 方法完成此操作。此方法接收一个会被立即执行的回调。在回调中的任何模型操作都不会同步到模型的索引：

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

有条件地让模型实例可搜索

有时可能只需要在某些条件下让模型可搜索。例如，假设有一个 App\Post 模型，它可以处于以下两种状态中的一种：「草稿」和「已发布」。可能只希望「已发布」的文章可以被搜索。可以在模型上定义一个 shouldBeSearchable 方法完成此操作：

public function shouldBeSearchable()
{
    return $this->isPublished();
}

搜索

可以使用 search 方法开始搜索模型。search 方法接收一个用于搜索模型的字符串。然后应该在搜索查询上链式调用 get 方法来获取与给定搜索查询相匹配的 Eloquent 模型：

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

由于 Scout 搜索返回一个 Eloquent 模型集合，因此甚至可以直接在路由或控制器中返回结果，它们会被自动转换为 JSON：

use Illuminate\Http\Request;

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

如果想要在结果被转换为 Eloquent 模型前获取原始的结果，应该使用 raw 方法：

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

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

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

Where 语句

Scout 允许您为搜索查询添加简单的「where」语句。目前，这些语句只支持基本的数字相等检查，主要用于通过拥有者 ID 限制搜索查询范围。由于搜索索引不是关系型数据库，因此目前不支持更高级的「where」语句：

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

分页

除了获取模型集合，还可以使用 paginate 方法对搜索结果分页。此方法会返回一个 Paginator 实例，就像 对传统 Eloquent 查询分页 一样：

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

可以将总数作为第一个参数传递给 paginate 方法来指定每页要获取多少个模型：

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

获取结果后，可以使用 Blade 显示结果并渲染页面，就像对传统 Eloquent 查询分页一样：

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

{{ $orders->links() }}

软删除

如果索引的模型是 软删除 并且需要搜索软删除的模型，可以将 config/scout.php 文件中的 soft_delete 选项设置为 true：

'soft_delete' => true,

当此配置项为 true 时，Scout 不会从搜索索引中删除软删除的模型。而是，会在索引的记录上设置一个隐藏的 __soft_deleted 属性。然后，可以在搜索时使用 withTrashed 或 onlyTrashed 方法获取软删除的记录：

// 获取结果时包括软删除的记录
$orders = App\Order::withTrashed()->search('Star Trek')->get();

// 获取结果时只包括软删除的记录
$orders = App\Order::onlyTrashed()->search('Star Trek')->get();

当使用 forceDelete 永久删除软删除的模型时，Scout 会从搜索索引中自动将其删除。

自定义引擎搜索行为

如果需要自定义引擎的搜索行为，可以将回调作为第二个参数传递给 search 方法。例如，可以使用此回调在搜索查询被发送给 Algolia 前在搜索选项中添加 GEO 位置数据：

use AlgoliaSearch\Index;

App\Order::search('Star Trek', function (Index $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 抽象类。此抽象类包含 7 个自定义引擎必须实现的方法：

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($results, $model);
abstract public function getTotalCount($results);

您可能会发现在 Laravel\Scout\Engines\AlgoliaEngine 类上查看这些方法的实现很有帮助。此类将为您提供一个好的起点，学习如何在自己的引擎中实现这些方法。

注册引擎

编写自定义引擎后，可以使用 Scout 引擎管理器的 extend 方法将其注册到 Scout。应该在 AppServiceProvider 的 boot 方法中调用 extend 方法，或者在应用使用的任何其它服务提供者中。例如，如果编写了 MySqlSearchEngine，可以像这样注册它：

use Laravel\Scout\EngineManager;

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

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

'driver' => 'mysql',

构造器宏

如果想要定义一个自定义构造器方法，可以在 Laravel\Scout\Builder 类上使用 macro 方法。通常情况下，「宏」应该在 服务提供者 的 boot 方法中定义：

namespace App\Providers;

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

class ScoutMacroServiceProvider extends ServiceProvider
{
    /**
     * 注册应用的 scout 宏
     *
     * @return void
     */
    public function boot()
    {
        Builder::macro('count', function () {
            return $this->engine->getTotalCount(
                $this->engine()->search($this)
            );
        });
    }
}

macro 方法接收一个名称作为其第一个参数，和一个闭包作为其第二个参数。当从 Laravel\Scout\Builder 的实现中调用宏名称时会执行宏的闭包：

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