Typesense 中文文档

# Laravel 全文搜索

Laravel Scout (opens new window) 是一个强大的扩展包，为 Laravel Eloquent (opens new window) ORM 模型提供了基于驱动程序的简单全文搜索解决方案。

Laravel Scout 原生支持 Typesense，本指南将重点介绍如何向现有 Laravel 项目添加 Laravel Scout Typesense 驱动，从而为你的 Laravel 应用程序添加全文搜索功能。

如果你想观看视频教程，这里有一个由 Aaron Francis (opens new window) 制作的视频：

# 先决条件

本指南将使用 Laravel Sail (opens new window)（一个允许你使用 Docker 运行 Laravel 应用程序的 CLI 工具）。

请确保你的机器上已安装 Docker。你可以按照 Docker 官方文档 (opens new window) 的说明进行安装。

要使用 Laravel Sail 创建新的 Laravel 项目，请遵循 Laravel 官方文档 (opens new window) 中的说明。

本指南将使用 Linux 环境，但你可以根据操作系统调整命令。

# 第一步：使用 Laravel Sail 创建新项目

如果用户没有指定特定服务，Laravel Sail 默认会使用一组默认服务 (opens new window)。在本指南中，我们将使用 PostgreSQL 数据库服务。以下命令用于通过 Laravel Sail 创建新项目：

此命令将创建一个名为 typesense-scout-example 的新 Laravel 项目，并启用 PostgreSQL 服务。然后您可以进入项目目录：

启动 Laravel Sail 的 Docker 容器：

并应用 User 模型的数据库迁移：

现在您可以通过浏览器访问 http://localhost 来查看 Laravel 应用程序。

# 步骤 2：安装 Laravel Scout Typesense 驱动

要安装 Laravel Scout Typesense 驱动，我们需要将这个包添加到你的 Laravel 项目中。可以通过运行以下命令来完成：

然后从列表中选择 typesense 驱动。

注意：Laravel Scout 中默认的 Typesense 版本是 0.25.2。如果你想使用最新版本，可以在 docker-compose.yml 文件中指定。例如，要使用版本 26.0，可以在 docker-compose.yml 文件中添加以下内容：

为了使更改生效，我们需要重新构建 Docker 容器：

# 步骤3：安装并配置 Laravel Scout

根据 Laravel Sail 文档 (opens new window)，要通过 Composer 安装 Laravel Scout，请运行以下命令：

你还需要安装 Typesense API 的官方 PHP 客户端 (opens new window)，运行以下命令：

接下来，发布 Laravel Scout 的配置文件：

然后修改 config/scout.php 文件，配置 Laravel Scout 使用 Typesense 驱动：

# 配置队列（可选）

虽然不是必须的，但你可以配置 Laravel Scout 使用队列 (opens new window)来处理索引和搜索操作。在本指南中，我们将使用 database 队列驱动，但你也可以选择官方 Laravel 文档 (opens new window)中提到的多种其他驱动。要配置 database 队列驱动，首先确保数据库中包含用于存储任务的表，运行以下命令：

接下来，在 .env 文件中配置 SCOUT_CONNECTION 环境变量以使用 database 队列驱动：

最后，配置 config/scout.php 文件以使用 database 队列驱动：

然后你可以运行队列工作器来处理队列中的任务：

这将在后台启动队列工作器，处理队列中的任务。有关队列工作器及其优势的更多信息，可以参考官方 Laravel 文档 (opens new window)。

# 步骤4：创建模型并迁移数据

接下来，让我们向 PostgreSQL 数据库添加一些数据。你可以使用任何数据集，但本指南将使用 Terenci Claramunt (@terencicp (opens new window)) 公开的 2013 至 2023 年 Steam 游戏数据集，你可以在这里 (opens new window)找到它，并将其保存在 data 文件夹中。

要使用这个数据集，你需要为 Steam 游戏创建一个 Eloquent 模型，并创建迁移文件、模型文件和控制器。可以使用以下命令：

这个命令将创建一个名为 Game 的 Eloquent 模型，同时生成迁移文件和资源控制器。现在我们来修改模型文件 app/Models/Game.php，包含 Steam 游戏数据集所需的字段：

同时修改迁移文件 database/migrations/**timestamp**_create_games_table.php，包含 Steam 游戏数据集所需的字段：

然后运行迁移命令，在 PostgreSQL 数据库中创建 games 表：

我们创建了一个简单的 bash 脚本 (opens new window)来将所有数据加载到 PostgreSQL 数据库。你可以将脚本添加到 scripts 文件夹中，并在终端运行它来用 Steam 游戏数据集填充 games 表。

# 第5步：使用 Laravel Scout 索引数据

要通过 Laravel Scout 索引数据，我们需要在 Game 模型中添加 Searchable trait，并创建一个 toSearchableArray 方法返回模型的可索引数据数组。只有当模型在数据库中的结构与 Typesense 中不同时才需要这样做，例如包含日期字段的模型。你可以按如下方式修改 app/Models/Game.php 文件：

然后在 config/scout.php 文件中定义 集合模式(Collection Schema)：

WARNING

不要忘记在 config.php 文件顶部使用 use App\Models\Game; 导入你的模型。这对 model-settings 的正常工作至关重要。

设置好 Laravel Scout 驱动后，所有后续的模型变更都会通过 Laravel Scout 提供的 Model Observer (opens new window) 自动同步到 Typesense。

为了验证是否正常工作，让我们在 Games 表中创建一条新记录。我们将使用 Laravel Tinker (opens new window)，这是一个可以交互式编写和执行 PHP 代码的 REPL 工具。你可以运行以下命令打开 Laravel Tinker：

然后在 Games 表中创建一条新记录：

然后你可以运行搜索查询来验证记录是否已被索引到 Typesense：

你应该能在搜索结果中看到你创建的记录。

# 动态搜索参数

您还可以动态设置 搜索参数 来实时搜索集合。例如，您可以设置 query_by 参数仅通过游戏的 Steam App ID 进行搜索：

# 步骤 6：回填现有数据

目前我们的设置会确保 未来 所有数据变更都能自动同步到 Typesense 中。

要将表中现有的数据回填到 Typesense，可以运行以下命令：

要测试一切是否正常工作，您可以运行一个搜索查询：

之后您可以根据偏好继续开发。您可以创建一个控制器来处理搜索请求，或者使用 Typesense InstantSearch Adapter (opens new window) 在前端使用 Instantsearch.js。如果您更喜欢使用 JavaScript 框架，可以使用 Inertia.js (opens new window) 创建 Vue.js、Svelte 或 React.js 前端。

# 示例

这个 Laravel 演示应用 (opens new window) 使用了 React Typescript 前端配合 Typesense InstantSearch Adapter，并通过 Laravel Scout 将数据从 Postgres 同步到 Typesense。

# 延伸阅读

← 文档站点搜索 →