教程 > Laravel 教程 > Laravel 常用Package 阅读：40

Laravel Scout

简介

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

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

安装

首先，我们通过 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 信息。配置好之后，还需要通过 Composer 包管理器安装 Algolia PHP SDK：

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

配置

配置模型索引

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

<?php

namespace App;

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

class Post extends Model
{
    use Searchable;

    /**
     * Get the index name for the model.
     *
     * @return string
     */
    public function searchableAs()
    {
        return 'posts_index';
    }
}

配置搜索数据

默认情况下，模型以完整的 toArray 格式持久化到搜索索引，如果我们想要自定义被持久化到搜索索引的数据，可以重写模型上的 toSearchableArray 方法：

<?php

namespace App;

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

class Post extends Model
{
    use Searchable;

    /**
     * Get the indexable data array for the model.
     *
     * @return array
     */
    public function toSearchableArray()
    {
        $array = $this->toArray();

        // Customize array...

        return $array;
    }
}

配置模型 ID

默认情况下，Scout 会使用模型的主键作为唯一 ID 将其存储到搜索索引中。如果你需要自定义这个行为，可以在模型类中重写 getScoutKey 和 getScoutKeyName 方法：

<?php

namespace App;

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

class User extends Model
{
    use Searchable;

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

    /**
     * Get the key name used to index the model.
     *
     * @return mixed
     */
    public function getScoutKeyName()
    {
        return 'email';
    }
}

识别用户

Scout 还允许我们在使用 Algolia 时自动识别用户。在 Algolia 面板中查看我们的搜索分析时，将经过身份验证的用户与搜索操作相关联可能会有所帮助。可以通过在.env文件中设置SCOUT_IDENTIFY为true来启用用户标识：

SCOUT_IDENTIFY=true

索引

批量导入

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

$ php artisan scout:import "App\Post"

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

$ php artisan scout:flush "App\Post"

添加记录

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

$order = new App\Order;
// ...
$order->save();

通过查询添加

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

// Adding via Eloquent query...
App\Order::where('price', '>', 100)->searchable();

// You may also add records via relationships...
$user->orders()->searchable();

// You may also add records via collections...
$orders->searchable();

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

更新记录

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

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

// Update the order...

$order->save();

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

// Updating via Eloquent query...
App\Order::where('price', '>', 100)->searchable();

// You may also update via relationships...
$user->orders()->searchable();

// You may also update via collections...
$orders->searchable();

删除记录

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

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

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

// Removing via Eloquent query...
App\Order::where('price', '>', 100)->unsearchable();

// You may also remove via relationships...
$user->orders()->unsearchable();

// You may also remove via collections...
$orders->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('Star Trek')->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('Star Trek')->raw();

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

$orders = App\Order::search('Star Trek')
    ->within('tv_shows_popularity_desc')
    ->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() }}

软删除

如果你的索引模型被软删除但是需要搜索软删除模型，可以设置配置文件 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（或者其他 service provider ）的 boot 方法中调用这个 extend 方法。例如，如果你编写了 MySqlSearchEngine，可以这样注册：

use Laravel\Scout\EngineManager;

/**
 * Bootstrap any application services.
 *
 * @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 Illuminate\Support\Facades\Response;
use Illuminate\Support\ServiceProvider;
use Laravel\Scout\Builder;

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();

 Laravel Sanctum

Laravel Socialite 

迹忆客计算机编程教程

Laravel Scout

简介

安装

队列

驱动预备知识

Algolia

配置

配置模型索引

配置搜索数据

配置模型 ID

识别用户

索引

批量导入

添加记录

通过查询添加

更新记录

删除记录

暂停索引

带条件的搜索模型实例

搜索

where 子句

分页

软删除

自定义引擎搜索

自定义引擎

编写引擎

注册引擎

构建器宏

查看笔记

Laravel Scout

简介

安装

队列

驱动预备知识

Algolia

配置

配置模型索引

配置搜索数据

配置模型 ID

识别用户

索引

批量导入

添加记录

通过查询添加

更新记录

删除记录

暂停索引

带条件的搜索模型实例

搜索

where 子句

分页

软删除

自定义引擎搜索

自定义引擎

编写引擎

注册引擎

构建器宏

 查看笔记

查看笔记