Laravel Scout

简介
安装
- 队列
驱动程序先决条件
配置
- 配置可搜索数据
数据库/集合引擎
- 数据库引擎
- 集合引擎
第三方引擎配置
第三方引擎索引
搜索
自定义引擎

简介

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

Scout 附带一个内置的 database 引擎，使用 MySQL / PostgreSQL 全文索引和 LIKE 子句搜索您现有的数据库——不需要外部服务。对于大多数应用程序，这就是您所需要的。有关 Laravel 中所有可用搜索选项的概述，请参阅搜索文档。

当您需要容错、分面过滤或大规模地理搜索等功能时，Scout 还包括 Algolia、Meilisearch 和 Typesense 的驱动程序。还提供了用于本地开发的"collection"驱动程序，您也可以自由编写自定义引擎。

安装

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

shell

composer require laravel/scout

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

shell

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

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

php

<?php

namespace App\Models;

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

class Post extends Model
{
    use Searchable;
}

队列

当使用非 database 或 collection 引擎的引擎时，您应该强烈考虑在使用库之前配置队列驱动程序。运行队列工作进程将允许 Scout 将所有同步模型信息到搜索索引的操作排队，从而为应用程序的 Web 界面提供更好的响应时间。

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

php

'queue' => true,

即使 queue 选项设置为 false，重要的是要记住某些 Scout 驱动程序（如 Algolia 和 Meilisearch）始终异步索引记录。换句话说，即使索引操作已在 Laravel 应用程序中完成，搜索引擎本身可能不会立即反映新的和更新的记录。

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

php

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

当然，如果您自定义 Scout 作业使用的连接和队列，您应该运行队列工作进程来处理该连接和队列上的作业：

shell

php artisan queue:work redis --queue=scout

驱动程序先决条件

Algolia

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

shell

composer require algolia/algoliasearch-client-php

Meilisearch

Meilisearch 是一个快速的开源搜索引擎。如果您不确定如何在本地机器上安装 Meilisearch，可以使用 Laravel Sail，这是 Laravel 官方支持的 Docker 开发环境。

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

shell

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

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

ini

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

有关 Meilisearch 的更多信息，请参阅 Meilisearch 文档。

此外，您应该通过查看 Meilisearch 关于二进制兼容性的文档来确保安装与您的 Meilisearch 二进制版本兼容的 meilisearch/meilisearch-php 版本。

WARNING

在使用 Meilisearch 的应用程序上升级 Scout 时，您应该始终查看 Meilisearch 服务本身的任何其他破坏性更改。

Typesense

Typesense 是一个闪电般快速的开源搜索引擎，支持关键词搜索、语义搜索、地理搜索和向量搜索。

您可以自托管 Typesense 或使用 Typesense Cloud。

要开始使用 Typesense 和 Scout，请通过 Composer 包管理器安装 Typesense PHP SDK：

shell

composer require typesense/typesense-php

然后，在应用程序的 .env 文件中设置 SCOUT_DRIVER 环境变量以及您的 Typesense 主机和 API 密钥凭据：

ini

SCOUT_DRIVER=typesense
TYPESENSE_API_KEY=masterKey
TYPESENSE_HOST=localhost

如果您使用 Laravel Sail，您可能需要调整 TYPESENSE_HOST 环境变量以匹配 Docker 容器名称。您也可以选择指定安装的端口、路径和协议：

ini

TYPESENSE_PORT=8108
TYPESENSE_PATH=
TYPESENSE_PROTOCOL=http

Typesense 集合的其他设置和架构定义可以在应用程序的 config/scout.php 配置文件中找到。有关 Typesense 的更多信息，请参阅 Typesense 文档。

配置

配置可搜索数据

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

php

<?php

namespace App\Models;

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

class Post extends Model
{
    use Searchable;

    /**
     * 获取模型的可索引数据数组。
     *
     * @return array<string, mixed>
     */
    public function toSearchableArray(): array
    {
        $array = $this->toArray();

        // 自定义数据数组...

        return $array;
    }
}

配置模型引擎

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

php

<?php

namespace App\Models;

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

class User extends Model
{
    use Searchable;

    /**
     * 获取用于索引模型的引擎。
     */
    public function searchableUsing(): Engine
    {
        return Scout::engine('meilisearch');
    }
}

数据库/集合引擎

数据库引擎

WARNING

数据库引擎目前支持 MySQL 和 PostgreSQL，两者都提供快速的全文本列索引支持。

database 引擎使用 MySQL / PostgreSQL 全文索引和 LIKE 子句直接搜索您现有的数据库。对于许多应用程序，这是添加搜索最简单、最实用的方式——不需要外部服务或额外的基础设施。

要使用数据库引擎，将 SCOUT_DRIVER 环境变量设置为 database：

ini

SCOUT_DRIVER=database

配置完成后，您可以定义可搜索数据并开始对模型执行搜索查询。与第三方引擎不同，数据库引擎不需要单独的索引步骤——它直接搜索您的数据库表。

自定义数据库搜索策略

默认情况下，数据库引擎将对您配置为可搜索的每个模型属性执行 LIKE 查询。但是，您可以为特定列分配更高效的搜索策略。SearchUsingFullText 属性将为该列使用数据库的全文索引，而 SearchUsingPrefix 只会匹配字符串的开头（example%）而不是搜索整个字符串（%example%）。

要定义此行为，请将 PHP 属性分配给模型的 toSearchableArray 方法。任何没有属性的列将继续使用默认的 LIKE 策略：

php

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

/**
 * 获取模型的可索引数据数组。
 *
 * @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

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

集合引擎

"collection" 引擎用于快速原型、极小的数据集（几百条记录）或运行测试。它从数据库检索所有可能的记录，并使用 Laravel 的 Str::is 辅助函数在 PHP 中过滤它们，因此不需要任何索引或数据库特定功能。对于超出简单用例的任何情况，您应该改用数据库引擎。

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

ini

SCOUT_DRIVER=collection

指定集合驱动程序作为首选驱动程序后，您可以开始对模型执行搜索查询。使用集合引擎时，不需要搜索引擎索引，例如为 Algolia、Meilisearch 或 Typesense 索引设定种子所需的索引。

与数据库引擎的区别

虽然数据库引擎使用全文索引和 LIKE 子句高效地查找匹配记录，但集合引擎提取所有记录并在 PHP 中过滤它们。集合引擎是最可移植的选项，因为它适用于 Laravel 支持的所有关系数据库（包括 SQLite 和 SQL Server）；但是，它比数据库引擎效率低得多，不应与大型数据集一起使用。

第三方引擎配置

以下配置选项仅在使用第三方搜索引擎（如 Algolia、Meilisearch 或 Typesense）时相关。如果您使用的是数据库引擎，可以跳过本节。

配置模型索引

使用第三方引擎时，每个 Eloquent 模型都与给定的搜索"索引"同步，该索引包含该模型的所有可搜索记录。默认情况下，每个模型将被持久化到与模型典型"表"名称匹配的索引中。通常，这是模型名称的复数形式；但是，您可以通过覆盖模型上的 searchableAs 方法自由自定义模型的索引：

php

<?php

namespace App\Models;

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

class Post extends Model
{
    use Searchable;

    /**
     * 获取与模型关联的索引名称。
     */
    public function searchableAs(): string
    {
        return 'posts_index';
    }
}

NOTE

searchableAs 方法在使用数据库引擎时无效，数据库引擎始终直接搜索模型的数据库表。

配置模型 ID

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

php

<?php

namespace App\Models;

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

class User extends Model
{
    use Searchable;

    /**
     * 获取用于索引模型的值。
     */
    public function getScoutKey(): mixed
    {
        return $this->email;
    }

    /**
     * 获取用于索引模型的键名。
     */
    public function getScoutKeyName(): mixed
    {
        return 'email';
    }
}

NOTE

getScoutKey 和 getScoutKeyName 方法在使用数据库引擎时无效，数据库引擎始终使用模型的主键。

Algolia

索引设置

有时您可能想在 Algolia 索引上配置其他设置。虽然您可以通过 Algolia UI 管理这些设置，但直接从应用程序的 config/scout.php 配置文件管理索引配置的所需状态有时更高效。

这种方法允许您通过应用程序的自动部署管道部署这些设置，避免手动配置并确保多个环境之间的一致性。您可以配置可过滤属性、排名、分面或任何其他支持的设置。

首先，在应用程序的 config/scout.php 配置文件中为每个索引添加设置：

php

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

'algolia' => [
    'id' => env('ALGOLIA_APP_ID', ''),
    'secret' => env('ALGOLIA_SECRET', ''),
    'index-settings' => [
        User::class => [
            'searchableAttributes' => ['id', 'name', 'email'],
            'attributesForFaceting'=> ['filterOnly(email)'],
            // 其他设置字段...
        ],
        Flight::class => [
            'searchableAttributes'=> ['id', 'destination'],
        ],
    ],
],

如果给定索引底层的模型可软删除并包含在 index-settings 数组中，Scout 将自动在该索引上包含对软删除模型进行分面的支持。如果您没有其他分面属性要为可软删除模型索引定义，您可以简单地为该模型在 index-settings 数组中添加一个空条目：

php

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

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

shell

php artisan scout:sync-index-settings

识别用户

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

ini

SCOUT_IDENTIFY=true

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

Meilisearch

索引设置

Meilisearch 要求您预先定义索引搜索设置，例如可过滤属性、可排序属性和其他支持的设置字段。

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

php

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'],
            // 其他设置字段...
        ],
        Flight::class => [
            'filterableAttributes'=> ['id', 'destination'],
            'sortableAttributes' => ['updated_at'],
        ],
    ],
],

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

php

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

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

shell

php artisan scout:sync-index-settings

可搜索数据类型

Meilisearch 只会对正确类型的数据执行过滤操作（>、< 等）。自定义可搜索数据时，应确保将数值转换为正确的类型：

php

public function toSearchableArray()
{
    return [
        'id' => (int) $this->id,
        'name' => $this->name,

Laravel Scout ​

简介 ​

安装 ​

队列 ​

驱动程序先决条件 ​

Algolia ​

Meilisearch ​

Typesense ​

配置 ​

配置可搜索数据 ​

配置模型引擎 ​

数据库/集合引擎 ​

数据库引擎 ​

自定义数据库搜索策略 ​

集合引擎 ​

与数据库引擎的区别 ​

第三方引擎配置 ​

配置模型索引 ​

配置模型 ID ​

Algolia ​

索引设置 ​

识别用户 ​

Meilisearch ​

索引设置 ​

可搜索数据类型 ​

Laravel Scout

简介

安装

队列

驱动程序先决条件

Algolia

Meilisearch

Typesense

配置

配置可搜索数据

配置模型引擎

数据库/集合引擎

数据库引擎

自定义数据库搜索策略

集合引擎

与数据库引擎的区别

第三方引擎配置

配置模型索引

配置模型 ID

Algolia

索引设置

识别用户

Meilisearch

索引设置

可搜索数据类型