全文搜索解决方案：Laravel Scout

简介

Laravel Scout 为 Eloquent 模型全文搜索实现提供了简单的、基于驱动的解决方案。通过使用模型观察者，Scout 会自动同步更新模型记录的索引。

目前，Scout 通过 Algolia 驱动提供搜索功能，不过，编写自定义驱动很简单，你可以很轻松地通过自己的搜索实现来扩展 Scout。

注：Algolia 是一个托管式的全文搜索引擎，我们可以通过其提供的 API 在网站和移动应用中快速实现实时搜索功能。Algolia 提供的服务是收费的，不过我们可以使用其免费版本进行测试，免费版本支持 1 万条记录/10 万次操作。

安装

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

composer require laravel/scout

安装完成后，需要通过 Artisan 命令 vendor:publish 发布 Scout 配置，该命令会发布配置文件 scout.php 到 config 目录：

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

最后，如果你想要某个模型支持 Scout 搜索，需要添加 Laravel\Scout\Searchable trait 到对应模型类，该 trait 会注册模型观察者来保持搜索驱动与模型记录数据的一致性：

<?php

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' => env('SCOUT_QUEUE', true),

驱动预备知识

Algolia

使用 Algolia 驱动的话，需要在配置文件 config/scout.php 中设置 Algolia 的 id 和 secret 信息（这些信息可以在注册登录 Algolia 之后在用户后台找到，分别对应 API Keys 下的 Application ID 和 Admin API Key）。配置好之后，还需要通过 Composer 包管理器安装 Algolia PHP SDK：

composer require algolia/algoliasearch-client-php:^2.2

配置

配置模型索引

每个 Eloquent 模型都是通过给定的搜索“索引”进行同步，该索引包含了所有可搜索的模型记录，换句话说，你可以将索引看作是一个 MySQL 数据表。默认情况下，每个模型都会被持久化到与模型对应表名（通常是模型名称的复数形式）相匹配的索引中，不过，你可以通过重写模型中的 searchableAs 方法来覆盖这一默认设置：

<?php

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

<?php

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

<?php

namespace App;

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

class User extends Model
{
    use Searchable;

    /**
     * Get the value used to index the model.
     *
     * @return mixed
     */
    public function getScoutKey()
    {
        return $this->email;
    }
}

索引

批量导入

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

php artisan scout:import "App\Post"

导入成功后，我们在 Algolia 后台就可以看到导入成功的索引数据：

flush 方法可用于从搜索索引中移除所有模型记录：

php artisan scout:flush "App\Post"

添加记录

添加 Laravel\Scout\Searchable trait 到模型之后，剩下需要做的就是保存模型实例，然后该实例会自动被添加到模型索引，如果你配置了 Scout 使用队列，该操作会被推送到队列在后台执行：

$post = new App\Post;

$post->title = 'Scout是什么';
$post->content = 'Scout是Laravel官方提供的全文搜索解决方案';
$post->user_id = 1;

$post->save();

模型数据保存之后，也会通过 Scout 同步到 Algolia：

通过查询添加

如果你想要通过 Eloquent 查询添加模型集合到搜索索引，可以在 Eloquent 查询之后追加 searchable 方法调用。searchable 方法会分组块进行查询并将结果添加到搜索索引。再次强调，如果你配置了 Scout 使用队列，所有的组块查询会被推送到队列在后台进行：

// 通过 Eloquent 查询添加...
App\Post::where('user_id', '>', 10)->searchable();

// 还可以通过关联关系添加记录...
$user->posts()->searchable();

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

searchable 方法会进行“upsert”操作，换句话说，如果模型记录已经存在于索引，则会被更新，如果不存在，才会被添加。

更新记录

要更新支持搜索的模型，只需更新模型实例的属性并保存模型到数据库。Scout 会自动持久化更新到搜索索引：

$post = App\Post::find(2);

$post->title = '学院君是谁';
$post->content = '学院君创建了Laravel学院，故而得名';

$post->save();

去 Algolia 查看索引数据，已更新：

还可以使用模型查询提供的 searchable 方法更新模型集合，如果模型在搜索索引中不存在，则会被创建：

// 通过 Eloquent 查询更新...
App\Post::where('user_id', '>', 10)->searchable();

// 还可以通过关联关系更新...
$user->posts()->searchable();

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

删除记录

要从索引中删除记录，只需从数据库中删除对应记录即可，这种删除方式甚至兼容软删除模型：

$post = App\Post::find(1);

$post->delete();

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

// 通过 Eloquent 查询移除...
App\Post::where('user_id', '>', 10)->unsearchable();

// 还可以通过关联关系移除...
$user->posts()->unsearchable();

// 还可以通过集合移除...
$posts->unsearchable();

暂停索引

有时候你需要在不同步模型数据到搜索索引的情况下执行批量的 Eloquent 操作，可以通过 withoutSyncingToSearch 方法来实现。该方法接收一个立即被执行的回调，该回调中出现的所有模型操作都不会同步到搜索索引：

App\Post::withoutSyncingToSearch(function () {
    // Perform model actions...
});

带条件的搜索模型实例

有时候你可能需要在特定条件下对模型进行搜索，例如，假设你有一个 App\Post 模型，它有两种状态：「default」和 「published」，你可能只想对「published」状态的文章进行搜索，要实现这个功能，可以在模型类中定义一个 shouldBeSearchable 方法：

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

shouldBeSearchable 只有在通过 save 方、查询和关联关系操作模型时才会应用。直接使用 searchable 方法让模型或集合变得可搜索将会覆盖 shouldBeSearchable 方法的结果：

// Will respect "shouldBeSearchable"...
App\Order::where('price', '>', 100)->searchable();

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

$order->save();

// Will override "shouldBeSearchable"...
$orders->searchable();

$order->searchable();

搜索

你可以通过 search 方法来搜索一个模型，该方法接收一个用于搜索模型的字符串，然后你还需要在这个搜索查询上调用一个 get 方法来获取与给定搜索查询相匹配的 Eloquent 模型：

$posts = App\Post::search('学院')->get();

由于 Scout 搜索返回的是 Eloquent 模型集合，你甚至可以直接从路由或控制器中返回结果，它们将会被自动转换为 JSON 格式：

use Illuminate\Http\Request;

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

搜索「学院」的话，返回两条搜索结果：

如果你想要获取原生搜索结果而不是转化后的 Eloquent 模型，可以使用 raw 方法：

$posts = App\Post::search('学院')->raw();

返回数据如下：

搜索查询使用模型类的 searchAs 方法指定的索引进行查询。不过，你也可以使用 within 方法指定一个自定义的索引进行搜索：

$posts = App\Post::search('学院')
    ->within('users_index')
    ->get();

where 子句

Scout 允许你添加简单的 where 子句到搜索查询，目前，这些子句仅支持简单的数值相等检查，由于搜索索引不是关系型数据库，更多高级的 where 子句暂不支持：

$posts = App\Post::search('学院')->where('user_id', 1)->get();

分页

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

$posts = App\Post::search('学院')->paginate();

返回结果如下：

你可以通过传入数量作为 paginate 方法的第一个参数来指定每页显示多少个模型：

$posts = App\Post::search('学院')->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 方法在搜索时获取软删除记录：

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

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

注：使用 forceDelete 永久删除软删除模型后，Scout 会自动将其从搜索索引中移除。

自定义引擎搜索

如果你需要自定义引擎的搜索行为可以传递一个回调到 search 方法作为第二个参数。例如，你可以在搜索查询被传递到 Algolia 之前使用这个回调添加地理位置数据到搜索选项：

use Algolia\AlgoliaSearch\SearchIndex;

App\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，该抽象类包含了 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);
abstract public function flush($model);

这些方法的实现可以参考 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' => env('SCOUT_DRIVER', 'mysql'),

构建器宏

如果你想要定义自定义的构建器方法，可以使用 Laravel\Scout\Builder 提供的 macro 方法。通常，我们在服务提供者的 boot 方法中定义「宏」：

<?php

namespace App\Providers;

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

class ScoutMacroServiceProvider extends ServiceProvider
{
    /**
     * Register the application's scout macros.
     *
     * @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();