[ Laravel 5.3 文档 ] 官方包 —— Laravel Scout

1、简介

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

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

2、安装

首先,我们通过Composer包管理器来安装Scout:

composer require laravel/scout

接下来,需要添加ScoutServiceProvider到配置文件config/app.phpproviders数组:

Laravel\Scout\ScoutServiceProvider::class,

注册Scout服务提供者之后,还需要通过Artisan命令vendor:publish发布Scout配置,该命令会发布配置文件scout.phpconfig目录:

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

最后,如果你想要模型变得可搜索,需要添加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' => true,

驱动预备知识

Algolia

使用Algolia驱动的话,需要在配置文件config/scout.php中设置Algolia的idsecret信息。配置好之后,还需要通过Composer包管理器安装Algolia PHP SDK:

composer require algolia/algoliasearch-client-php

3、配置

配置模型索引

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

4、索引

批量导入

如果你想要安装Scout到已存在的项目,你可能已经有了想要导入搜索驱动的数据库记录,Scout提供了Artisan命令import用于导入所有已存在的数据到搜索索引:

php artisan scout:import "App\Post"

添加记录

添加Laravel\Scout\Searchabletrait到模型之后,剩下需要做的就是保存模型实例,然后该实例会自动被添加到模型索引,如果你配置了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方法还可以进行“upsort”操作,换句话说,如果模型记录已经存在于索引,则会被更新,如果不存在,则会被添加。

更新记录

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

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

// 更新订单...

$order->save();

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

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

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

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

移除记录

要从索引中移除记录,只需从数据库中删除记录即可,这种移除方式甚至兼容软删除模型:

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

$order->delete();

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

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

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

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

暂停索引

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

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

5、搜索

你可以通过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();
});

where子句

Scout允许你添加简单的where子句到搜索查询,目前,这些子句仅支持简单的数值相等检查,由于搜索索引不是关系型数据库,更多高级的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() }}

6、自定义引擎

编写引擎

如果某个内置的Scout搜索引擎不满足你的需求,可以编写自定义的引擎并将其注册到Scout,自定义的引擎需要继承自抽象类Laravel\Scout\Engines\Engine,该抽象类包含了5个自定义引擎必须实现的方法:

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 map($results, $model);

这5个方法的实现可以参考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' => 'mysql',

学院君

学院君 has written 550 articles

资深PHP工程师,Laravel学院院长