Laravel 5.7 中文文档

简体中文

English

简体中文

English

主题

Laravel Scout ​

介绍 ​

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

目前，Scout 附带一个 Algolia 驱动程序；然而，编写自定义驱动程序很简单，您可以自由扩展 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;

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

class Post extends Model
{
    use Searchable;
}

队列 ​

虽然使用 Scout 并不严格要求，但在使用该库之前，您应该强烈考虑配置一个 队列驱动程序。运行队列工作程序将允许 Scout 将所有操作排队，以将您的模型信息同步到搜索索引，从而为您的应用程序的 Web 界面提供更好的响应时间。

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

php
'queue' => true,

驱动程序先决条件 ​

Algolia ​

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

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

配置 ​

配置模型索引 ​

每个 Eloquent 模型都与给定的搜索“索引”同步，该索引包含该模型的所有可搜索记录。换句话说，您可以将每个索引视为一个 MySQL 表。默认情况下，每个模型将被持久化到与模型的典型“表”名称匹配的索引中。通常，这是模型名称的复数形式；但是，您可以通过覆盖模型上的 searchableAs 方法来自定义模型的索引：

php
<?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
<?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
<?php

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 提供了一个 import Artisan 命令，您可以使用它将所有现有记录导入到搜索索引中：

php
php artisan scout:import "App\Post"

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

php
php artisan scout:flush "App\Post"

添加记录 ​

一旦您将 Laravel\Scout\Searchable trait 添加到模型中，您所需要做的就是 save 一个模型实例，它将自动添加到您的搜索索引中。如果您已配置 Scout 使用队列，此操作将由您的队列工作程序在后台执行：

php
$order = new App\Order;

// ...

$order->save();

通过查询添加 ​

如果您想通过 Eloquent 查询将一组模型添加到搜索索引中，可以将 searchable 方法链接到 Eloquent 查询上。searchable 方法将 分块查询结果 并将记录添加到搜索索引中。同样，如果您已配置 Scout 使用队列，所有分块将由您的队列工作程序在后台添加：

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

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

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

searchable 方法可以被视为“upsert”操作。换句话说，如果模型记录已经在您的索引中，它将被更新。如果它不存在于搜索索引中，它将被添加到索引中。

更新记录 ​

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

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

// 更新订单...

$order->save();

您还可以在 Eloquent 查询上使用 searchable 方法来更新一组模型。如果模型不存在于您的搜索索引中，它们将被创建：

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

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

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

删除记录 ​

要从索引中删除记录，请从数据库中 delete 模型。此删除形式甚至与 软删除 模型兼容：

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

$order->delete();

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

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

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

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

暂停索引 ​

有时您可能需要对模型执行一批 Eloquent 操作，而无需将模型数据同步到您的搜索索引。您可以使用 withoutSyncingToSearch 方法来执行此操作。此方法接受一个将立即执行的回调。回调中发生的任何模型操作都不会同步到模型的索引：

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

有条件的可搜索模型实例 ​

有时您可能只需要在某些条件下使模型可搜索。例如，假设您有一个 App\Post 模型，它可能处于两种状态之一：“草稿”和“已发布”。您可能只希望允许“已发布”的帖子可搜索。为此，您可以在模型上定义一个 shouldBeSearchable 方法：

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

shouldBeSearchable 方法仅在通过 save 方法、查询或关系操作模型时应用。直接使用 searchable 方法使模型或集合可搜索将覆盖 shouldBeSearchable 方法的结果：

php
// 将尊重 "shouldBeSearchable"...
App\Order::where('price', '>', 100)->searchable();

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

$order->save();

// 将覆盖 "shouldBeSearchable"...
$orders->searchable();

$order->searchable();

搜索 ​

您可以使用 search 方法开始搜索模型。search 方法接受一个用于搜索模型的字符串。然后，您应该将 get 方法链接到搜索查询上，以检索与给定搜索查询匹配的 Eloquent 模型：

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

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

php
use Illuminate\Http\Request;

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

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

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

搜索查询通常将在模型的 searchableAs 方法指定的索引上执行。但是，您可以使用 within 方法指定应搜索的自定义索引：

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

Where 子句 ​

Scout 允许您向搜索查询添加简单的 "where" 子句。目前，这些子句仅支持基本的数字相等检查，主要用于通过租户 ID 限制搜索查询。由于搜索索引不是关系数据库，目前不支持更高级的 "where" 子句：

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

分页 ​

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

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

您可以通过将数量作为第一个参数传递给 paginate 方法来指定每页检索多少个模型：

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

一旦您检索到结果，您可以显示结果并使用 Blade 渲染页面链接，就像您分页传统的 Eloquent 查询一样：

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

{{ $orders->links() }}

软删除 ​

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

php
'soft_delete' => true,

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

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

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

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

自定义引擎搜索 ​

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

php
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 抽象类。此抽象类包含七个方法，您的自定义引擎必须实现这些方法：

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

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

注册引擎 ​

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

php
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',

构建器宏 ​

如果您想定义一个自定义构建器方法，可以在 Laravel\Scout\Builder 类上使用 macro 方法。通常，“宏”应在 服务提供者 的 boot 方法中定义：

php
<?php

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 实现中调用宏名称时，将执行宏的闭包：

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

版权所有 © 2024-2025 laravel.wiki