Laravel 侦察兵

Introduction
Installation
- 驱动程序先决条件
- Queueing
Configuration
数据库/收集引擎
- 数据库引擎
- 收集引擎
Indexing
Searching
定制引擎
生成器宏

Introduction

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

目前，Scout 附带Algolia,MeiliSearch, 和 MySQL / PostgreSQL (database) 驱动程序。此外，Scout 包含一个专为本地开发使用而设计的“集合”驱动程序，不需要任何外部依赖项或第三方服务。此外，编写自定义驱动程序很简单，您可以使用自己的搜索实现自由扩展 Scout。

Installation

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

composer require laravel/scout

安装 Scout 后，您应该使用以下命令发布 Scout 配置文件vendor:publish 工匠命令。此命令将发布scout.php 配置文件到您的应用程序的config 目录：

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

最后，添加Laravel\Scout\Searchable 您希望使其可搜索的模型的特征。此特征将注册一个模型观察器，该观察器将自动使模型与您的搜索驱动程序保持同步：

<?php

namespace App\Models;

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

class Post extends Model
{
    use Searchable;
}

驱动程序先决条件

Algolia

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

composer require algolia/algoliasearch-client-php

MeiliSearch

MeiliSearch 是一个速度极快的开源搜索引擎。如果您不确定如何在本地计算机上安装 MeiliSearch，您可以使用Laravel 风帆，Laravel官方支持的Docker开发环境。

使用 MeiliSearch 驱动程序时，您需要通过 Composer 包管理器安装 MeiliSearch PHP SDK：

composer require meilisearch/meilisearch-php http-interop/http-factory-guzzle

然后，设置SCOUT_DRIVER 环境变量以及您的 MeiliSearchhost 和key 您的应用程序中的凭据.env 文件：

SCOUT_DRIVER=meilisearch
MEILISEARCH_HOST=http://127.0.0.1:7700
MEILISEARCH_KEY=masterKey

有关 MeiliSearch 的更多信息，请参阅美丽搜索文档.

此外，您应该确保安装了meilisearch/meilisearch-php 通过检查与您的 MeiliSearch 二进制版本兼容MeiliSearch 关于二进制兼容性的文档.

Warning
在使用 MeiliSearch 的应用程序上升级 Scout 时，您应该始终查看任何其他重大更改到 MeiliSearch 服务本身。

Queueing

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

配置队列驱动程序后，设置queue 你的选项config/scout.php 配置文件到true:

'queue' => true,

即使当queue 选项设置为false, 重要的是要记住一些 Scout 驱动程序，如 Algolia 和 Meilisearch 总是异步索引记录。这意味着，即使索引操作已在您的 Laravel 应用程序中完成，搜索引擎本身也可能不会立即反映新的和更新的记录。

要指定您的 Scout 作业使用的连接和队列，您可以定义queue 作为数组的配置选项：

'queue' => [
    'connection' => 'redis',
    'queue' => 'scout'
],

Configuration

配置模型索引

每个 Eloquent 模型都与给定的搜索“索引”同步，该索引包含该模型的所有可搜索记录。换句话说，你可以把每个索引想象成一张 MySQL 表。默认情况下，每个模型都将保存到与模型的典型“表”名称匹配的索引中。通常，这是型号名称的复数形式；但是，您可以通过覆盖searchableAs 模型上的方法：

<?php

namespace App\Models;

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

class Post extends Model
{
    use Searchable;

    /**
     * Get the name of the index associated with the model.
     */
    public function searchableAs(): string
    {
        return 'posts_index';
    }
}

配置可搜索数据

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

<?php

namespace App\Models;

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<string, mixed>
     */
    public function toSearchableArray(): array
    {
        $array = $this->toArray();

        // Customize the data array...

        return $array;
    }
}

某些搜索引擎如美丽搜索只会进行过滤操作（>,<等）在正确类型的数据上。因此，在使用这些搜索引擎和自定义您的可搜索数据时，您应该确保将数值转换为正确的类型：

public function toSearchableArray()
{
    return [
        'id' => (int) $this->id,
        'name' => $this->name,
        'price' => (float) $this->price,
    ];
}

配置可过滤数据和索引设置（美丽搜索）

与 Scout 的其他驱动程序不同，MeiliSearch 需要您预先定义索引搜索设置，例如可过滤属性、可排序属性和其他支持的设置字段.

可过滤属性是您计划在调用 Scout 时过滤的任何属性where 方法，而可排序属性是您计划在调用 Scout 时作为排序依据的任何属性orderBy 方法。要定义索引设置，请调整index-settings 你的一部分meilisearch 应用程序中的配置条目scout 配置文件：

use App\Models\User;
use App\Models\Flight;

'meilisearch' => [
    'host' => env('MEILISEARCH_HOST', 'http://localhost:7700'),
    'key' => env('MEILISEARCH_KEY', null),
    'index-settings' => [
        User::class => [
            'filterableAttributes'=> ['id', 'name', 'email'],
            'sortableAttributes' => ['created_at'],
            // Other settings fields...
        ],
        Flight::class => [
            'filterableAttributes'=> ['id', 'destination'],
            'sortableAttributes' => ['updated_at'],
        ],
    ],
],

如果给定索引下的模型是软删除的并且包含在index-settings 数组，Scout 将自动支持对该索引上的软删除模型进行过滤。如果您没有其他可过滤或可排序的属性来为软删除模型索引定义，您可以简单地添加一个空条目到index-settings 该模型的数组：

'index-settings' => [
    Flight::class => []
],

配置应用程序的索引设置后，您必须调用scout:sync-index-settings 工匠命令。此命令将通知美丽搜索您当前配置的索引设置。为方便起见，您可能希望将此命令作为部署过程的一部分：

php artisan scout:sync-index-settings

配置模型 ID

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

<?php

namespace App\Models;

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

class User extends Model
{
    use Searchable;

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

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

配置每个模型的搜索引擎

搜索时，Scout 通常会使用应用程序中指定的默认搜索引擎scout 配置文件。但是，可以通过覆盖searchableUsing 模型上的方法：

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Engines\Engine;
use Laravel\Scout\EngineManager;
use Laravel\Scout\Searchable;

class User extends Model
{
    use Searchable;

    /**
     * Get the engine used to index the model.
     */
    public function searchableUsing(): Engine
    {
        return app(EngineManager::class)->engine('meilisearch');
    }
}

识别用户

Scout 还允许您在使用时自动识别用户Algolia.在 Algolia 的仪表板中查看搜索分析时，将经过身份验证的用户与搜索操作相关联可能会有所帮助。您可以通过定义一个SCOUT_IDENTIFY 环境变量为true 在你的应用程序中.env 文件：

SCOUT_IDENTIFY=true

启用此功能还会将请求的 IP 地址和经过身份验证的用户的主要标识符传递给 Algolia，以便此数据与用户发出的任何搜索请求相关联。

数据库/收集引擎

数据库引擎

Warning
数据库引擎目前支持 MySQL 和 PostgreSQL。

如果您的应用程序与中小型数据库交互或工作量较小，您可能会发现使用 Scout 的“数据库”引擎更方便。当从现有数据库中筛选结果时，数据库引擎将使用“where like”子句和全文索引来确定适用于您的查询的搜索结果。

要使用数据库引擎，您可以简单地设置SCOUT_DRIVER 环境变量到database，或指定database 直接在您的应用程序中驱动scout 配置文件：

SCOUT_DRIVER=database

一旦将数据库引擎指定为首选驱动程序，就必须配置您的可搜索数据.然后，你可以开始执行搜索查询针对您的模型。使用数据库引擎时，不需要搜索引擎索引，例如种子 Algolia 或 MeiliSearch 索引所需的索引。

自定义数据库搜索策略

默认情况下，数据库引擎将对您拥有的每个模型属性执行“where like”查询配置为可搜索.但是，在某些情况下，这可能会导致性能不佳。因此，可以配置数据库引擎的搜索策略，使某些指定的列使用全文搜索查询或仅使用“where like”约束来搜索字符串的前缀（example%) 而不是在整个字符串中搜索 (%example%).

要定义此行为，您可以将 PHP 属性分配给模型的toSearchableArray 方法。任何未分配额外搜索策略行为的列将继续使用默认的“where like”策略：

use Laravel\Scout\Attributes\SearchUsingFullText;
use Laravel\Scout\Attributes\SearchUsingPrefix;

/**
 * Get the indexable data array for the model.
 *
 * @return array<string, mixed>
 */
#[SearchUsingPrefix(['id', 'email'])]
#[SearchUsingFullText(['bio'])]
public function toSearchableArray(): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        'bio' => $this->bio,
    ];
}

Warning
在指定列应使用全文查询约束之前，请确保已为该列分配了全文索引.

收集引擎

虽然您在本地开发期间可以自由使用 Algolia 或 MeiliSearch 搜索引擎，但您可能会发现使用“集合”引擎更方便上手。收集引擎将使用“where”子句和收集过滤来自现有数据库的结果来确定适用于您的查询的搜索结果。使用此引擎时，没有必要“索引”您的可搜索模型，因为它们会从您的本地数据库中简单地检索出来。

要使用收集引擎，您可以简单地设置SCOUT_DRIVER 环境变量到collection，或指定collection 直接在您的应用程序中驱动scout 配置文件：

SCOUT_DRIVER=collection

一旦您将收集驱动程序指定为您的首选驱动程序，您就可以开始执行搜索查询针对您的模型。使用收集引擎时，不需要搜索引擎索引，例如种子 Algolia 或 MeiliSearch 索引所需的索引。

与数据库引擎的区别

乍一看，“数据库”和“集合”引擎非常相似。它们都直接与您的数据库交互以检索搜索结果。但是，收集引擎不使用全文索引或LIKE 用于查找匹配记录的子句。相反，它提取所有可能的记录并使用 Laravel 的Str::is 确定搜索字符串是否存在于模型属性值中的助手。

集合引擎是最便携的搜索引擎，因为它适用于 Laravel 支持的所有关系数据库（包括 SQLite 和 SQL Server）；但是，它的效率低于 Scout 的数据库引擎。

Indexing

批量导入

如果您正在将 Scout 安装到现有项目中，您可能已经拥有需要导入到索引中的数据库记录。 Scout 提供了一个scout:import 可用于将所有现有记录导入搜索索引的 Artisan 命令：

php artisan scout:import "App\Models\Post"

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

php artisan scout:flush "App\Models\Post"

修改导入查询

如果您想修改用于检索所有模型以进行批量导入的查询，您可以定义一个makeAllSearchableUsing 模型上的方法。这是添加导入模型之前可能需要的任何急切关系加载的好地方：

use Illuminate\Database\Eloquent\Builder;

/**
 * Modify the query used to retrieve models when making all of the models searchable.
 */
protected function makeAllSearchableUsing(Builder $query): Builder
{
    return $query->with('author');
}

添加记录

一旦你添加了Laravel\Scout\Searchable 模型的特征，您需要做的就是save 或者create 一个模型实例，它将自动添加到您的搜索索引中。如果您已将 Scout 配置为使用队列此操作将由您的队列工作人员在后台执行：

use App\Models\Order;

$order = new Order;

// ...

$order->save();

通过查询添加记录

如果你想通过 Eloquent 查询将模型集合添加到搜索索引，你可以链接searchable 方法到雄辩的查询。这searchable 方法将分块结果查询并将记录添加到您的搜索索引。同样，如果您已将 Scout 配置为使用队列，则所有块都将由您的队列工作者在后台导入：

use App\Models\Order;

Order::where('price', '>', 100)->searchable();

您也可以致电searchable Eloquent 关系实例上的方法：

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

或者，如果你已经在内存中有一个 Eloquent 模型的集合，你可以调用searchable 集合实例上的方法将模型实例添加到它们相应的索引：

$orders->searchable();

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

更新记录

要更新可搜索模型，您只需要更新模型实例的属性和save 模型到你的数据库。 Scout 会自动将更改保存到您的搜索索引中：

use App\Models\Order;

$order = Order::find(1);

// Update the order...

$order->save();

您还可以调用searchable Eloquent 查询实例上的方法来更新模型集合。如果您的搜索索引中不存在这些模型，则会创建它们：

Order::where('price', '>', 100)->searchable();

如果您想更新关系中所有模型的搜索索引记录，您可以调用searchable 在关系实例上：

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

或者，如果你已经在内存中有一个 Eloquent 模型的集合，你可以调用searchable 集合实例上的方法更新相应索引中的模型实例：

$orders->searchable();

删除记录

要从索引中删除记录，您可以简单地delete 来自数据库的模型。即使您使用软删除楷模：

use App\Models\Order;

$order = Order::find(1);

$order->delete();

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

Order::where('price', '>', 100)->unsearchable();

如果你想删除关系中所有模型的搜索索引记录，你可以调用unsearchable 在关系实例上：

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

或者，如果你已经在内存中有一个 Eloquent 模型的集合，你可以调用unsearchable 集合实例上的方法从相应的索引中删除模型实例：

$orders->unsearchable();

暂停索引

有时您可能需要在不将模型数据同步到搜索索引的情况下对模型执行一批 Eloquent 操作。您可以使用withoutSyncingToSearch 方法。此方法接受将立即执行的单个闭包。闭包中发生的任何模型操作都不会同步到模型的索引：

use App\Models\Order;

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

有条件的可搜索模型实例

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

/**
 * Determine if the model should be searchable.
 */
public function shouldBeSearchable(): bool
{
    return $this->isPublished();
}

这shouldBeSearchable 方法仅在通过save 和create 方法、查询或关系。使用searchable 方法将覆盖的结果shouldBeSearchable 方法。

Warning
这shouldBeSearchable 当使用 Scout 的“数据库”引擎时，该方法不适用，因为所有可搜索的数据始终存储在数据库中。要在使用数据库引擎时实现类似的行为，您应该使用where子句反而。

Searching

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

use App\Models\Order;

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

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

use App\Models\Order;
use Illuminate\Http\Request;

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

如果您想在将原始搜索结果转换为 Eloquent 模型之前获得原始搜索结果，您可以使用raw 方法：

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

自定义索引

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

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

Where 子句

Scout 允许您向搜索查询添加简单的“where”子句。目前，这些子句仅支持基本的数字相等性检查，主要用于通过所有者 ID 确定搜索查询的范围：

use App\Models\Order;

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

您可以使用whereIn 将结果限制为一组给定值的方法：

$orders = Order::search('Star Trek')->whereIn(
    'status', ['paid', 'open']
)->get();

由于搜索索引不是关系数据库，因此目前不支持更高级的“where”子句。

Warning 如果您的应用程序使用 MeiliSearch，您必须配置您的应用程序的可过滤属性在使用 Scout 的“where”子句之前。

Pagination

除了检索模型集合之外，您还可以使用paginate 方法。这个方法会返回一个Illuminate\Pagination\LengthAwarePaginator 就像你有对传统的 Eloquent 查询进行分页:

use App\Models\Order;

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

您可以通过将数量作为第一个参数传递给paginate 方法：

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

检索到结果后，您可以显示结果并使用以下方法呈现页面链接Blade 就像您对传统的 Eloquent 查询进行分页一样：

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

{{ $orders->links() }}

当然，如果你想以 JSON 格式检索分页结果，你可以直接从路由或控制器返回分页器实例：

use App\Models\Order;
use Illuminate\Http\Request;

Route::get('/orders', function (Request $request) {
    return Order::search($request->input('query'))->paginate(15);
});

Warning
由于搜索引擎不知道您的 Eloquent 模型的全局范围定义，因此您不应在使用 Scout 分页的应用程序中使用全局范围。或者，您应该在通过 Scout 搜索时重新创建全局范围的约束。

软删除

如果您的索引模型是软删除你需要搜索你的软删除模型，设置soft_delete 的选项config/scout.php 配置文件到true:

'soft_delete' => true,

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

use App\Models\Order;

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

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

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

自定义引擎搜索

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

use Algolia\AlgoliaSearch\SearchIndex;
use App\Models\Order;

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

自定义 Eloquent 结果查询

在 Scout 从应用程序的搜索引擎中检索到匹配的 Eloquent 模型列表后，Eloquent 用于通过主键检索所有匹配模型。您可以通过调用query 方法。这query 方法接受一个闭包，该闭包将接收 Eloquent 查询生成器实例作为参数：

use App\Models\Order;
use Illuminate\Database\Eloquent\Builder;

$orders = Order::search('Star Trek')
    ->query(fn (Builder $query) => $query->with('invoices'))
    ->get();

由于此回调是在已从应用程序的搜索引擎中检索到相关模型后调用的，因此query 方法不应用于“过滤”结果。相反，你应该使用侦察 where 子句.

定制引擎

编写引擎

如果内置的 Scout 搜索引擎之一不能满足您的需要，您可以编写自己的自定义引擎并在 Scout 中注册。你的引擎应该扩展Laravel\Scout\Engines\Engine 抽象类。这个抽象类包含您的自定义引擎必须实现的八个方法：

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

您可能会发现在Laravel\Scout\Engines\AlgoliaEngine 班级。本课程将为您提供一个很好的起点，让您了解如何在您自己的引擎中实现这些方法中的每一个。

注册引擎

编写自定义引擎后，您可以使用extend Scout 引擎管理器的方法。 Scout 的引擎管理器可能是从 Laravel 服务容器中解析出来的。你应该打电话给extend 方法来自boot 你的方法App\Providers\AppServiceProvider 您的应用程序使用的类或任何其他服务提供者：

use App\ScoutExtensions\MySqlSearchEngine;
use Laravel\Scout\EngineManager;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    resolve(EngineManager::class)->extend('mysql', function () {
        return new MySqlSearchEngine;
    });
}

注册引擎后，您可以将其指定为默认 Scoutdriver 在你的应用程序中config/scout.php 配置文件：

'driver' => 'mysql',

生成器宏

如果您想定义自定义 Scout 搜索构建器方法，您可以使用macro 上的方法Laravel\Scout\Builder 班级。通常，“宏”应该在一个服务供应商 boot 方法：

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

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Builder::macro('count', function () {
        return $this->engine()->getTotalCount(
            $this->engine()->search($this)
        );
    });
}

这macro 函数接受一个宏名作为它的第一个参数，一个闭包作为它的第二个参数。宏的闭包将在调用宏名称时执行Laravel\Scout\Builder 执行：

use App\Models\Order;

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

Laravel 侦察兵

#Introduction

#Installation

#驱动程序先决条件

Algolia

MeiliSearch

#Queueing

#Configuration

#配置模型索引

#配置可搜索数据

配置可过滤数据和索引设置（美丽搜索）

#配置模型 ID

#配置每个模型的搜索引擎

#识别用户

#数据库/收集引擎

#数据库引擎

自定义数据库搜索策略

#收集引擎