Flarum源码解析

步子哥

开个专门的帖子来记录对Flarum源码的解读过程。

步子哥

在 class AbstractModel 这个类中，Callbacks 容器用于存储在特定事件发生时需要执行的回调函数。具体来说，afterSaveCallbacks 和 afterDeleteCallbacks 是两个主要的回调容器，分别用于在模型保存和删除后执行自定义逻辑。

具体功能：

事件驱动：通过使用回调函数，开发者可以在模型的生命周期中插入自定义逻辑。例如，在模型保存后执行某些操作（如发送通知、更新其他数据等）。
灵活性：回调函数可以根据需要动态添加，允许开发者在运行时定义行为，而不需要修改模型的核心代码。这种灵活性使得代码更具可维护性和可扩展性。
分离关注点：使用回调函数可以将业务逻辑与模型的主要功能分离，使得代码更加清晰和易于理解。

步子哥

addConnection 方法用于在数据库管理器中添加一个新的数据库连接。具体来说，在 Laravel 的 Eloquent ORM 中，addConnection 方法的作用如下：

注册数据库连接：通过调用 addConnection([imath:0]config, 'flarum')，将一个新的数据库连接配置添加到数据库管理器中。这里的 [/imath:0]config 是一个数组，包含了连接所需的配置信息（如数据库驱动、主机名、数据库名、用户名、密码等）。

$config = [
    'driver' => 'mysql',
    'host' => '127.0.0.1',
    'database' => 'flarum',
    'username' => 'root',
    'password' => '',
    'charset' => 'utf8mb4',
    'collation' => 'utf8mb4_unicode_ci',
    'prefix' => '',
    'strict' => true,
];

命名连接：第二个参数 'flarum' 是为这个连接指定的名称。这个名称可以在后续的数据库操作中引用，以便于选择和使用特定的连接。
支持多数据库：通过 addConnection 方法，应用程序可以同时支持多个数据库连接。例如，可以在同一个应用中连接到不同的数据库，或者在不同的环境（如开发、测试、生产）中使用不同的数据库配置。

步子哥

与 utf8mb4_general_ci 的比较：utf8mb4_general_ci 是另一种不区分大小写的排序规则，但它的排序和比较规则不如 utf8mb4_unicode_ci 精确。utf8mb4_unicode_ci 更加符合 Unicode 标准，适用于需要精确比较的场景。

步子哥

在 Laravel 中，singleton 函数用于注册一个服务容器中的单例实例。具体来说，singleton 的作用和理解可以从以下几个方面来看：

单例模式：singleton 方法实现了单例模式，这意味着在整个应用程序生命周期中，只有一个实例会被创建和使用。每次请求这个服务时，都会返回同一个实例，而不是每次都创建一个新的实例。
服务容器：Laravel 的服务容器是一个用于管理类依赖和执行依赖注入的工具。通过 singleton 方法，开发者可以将类或接口绑定到容器中，以便在需要时获取。
依赖注入：当你在类中请求一个依赖（例如通过构造函数注入或方法注入）时，Laravel 会自动从服务容器中解析出这个依赖。如果这个依赖是通过 singleton 注册的，Laravel 会确保返回的是同一个实例。
性能：使用单例可以减少内存开销和对象创建的开销，特别是对于那些创建成本较高的对象。因为在整个应用程序中只会创建一次实例，后续的请求都可以复用这个实例。

步子哥

$ability ??= '*';

这里的两个问号的意思是：

基本用法：?? 运算符用于检查左侧的变量是否存在且不为 null。如果存在且不为 null，则返回该变量的值；否则返回右侧的值。
结合赋值：在 ﹩ability ??= '*' 中，??= 是一种简写形式，表示如果 ﹩ability 变量不存在或为 null，则将其赋值为 '*'。如果 ﹩ability 已经有值（即不为 null），则保持原值不变。

步子哥

AbstractModel.php 是 Flarum 框架中用于建立数据库模型的抽象基类，继承自 Eloquent 模型。该类的主要功能和特点如下：

自动加载和命名空间: 使用了 Flarum\Database 命名空间。
时间戳: 默认禁用了时间戳（[imath:0]timestamps = false）。
回调函数: 包含在模型保存和删除后执行的回调函数数组（[/imath:0]afterSaveCallbacks 和 [imath:0]afterDeleteCallbacks）。
自定义类型转换: 允许为模型定义自定义的类型转换（[/imath:0]customCasts）。
默认属性: 支持为模型定义默认属性（[imath:0]defaults）。
表别名: 在查询中可以使用表别名（[/imath:0]tableAlias）。
唯一键: 如果模型有唯一键，可以在 $uniqueKeys 中定义。
引导方法: 在模型保存和删除后，依次执行相应的回调函数。
构造函数: 初始化模型属性，并合并所有父类的默认属性。
类型转换方法: 获取模型的所有类型转换，包括自定义类型转换。
回调注册方法: 提供方法注册在模型保存和删除后的回调函数。
回调释放方法: 提供方法释放并执行保存和删除后的回调函数。
新模型查询: 支持在查询中使用表别名。
列限定: 确保列名在查询中是合格的。
表别名回调: 提供方法在回调中使用表别名。
新集合: 返回自定义的集合类。
序列化: 在模型序列化时，清空回调函数数组，因为闭包无法被序列化。

详细代码可以在这里查看。

步子哥

DatabaseServiceProvider.php 是 Flarum 框架中的数据库服务提供者类，继承自 AbstractServiceProvider，主要用于注册和配置数据库相关的服务。它的主要功能包括：

注册服务:
- 注册 Eloquent 工厂 (registerEloquentFactory)
- 注册查询构建器宏 (registerBuilderMacros)
- 注册数据库管理器 (Manager)
- 注册连接解析器 (ConnectionResolverInterface)
- 注册数据库连接 (ConnectionInterface)
- 注册迁移库 (MigrationRepositoryInterface)
- 注册模型私有检查器 (flarum.database.model_private_checkers)
宏功能:
- 为不同的数据库驱动（MySQL、MariaDB、PostgreSQL、SQLite）注册 when 和 unless 宏，用于在特定驱动下执行回调函数。
Eloquent 工厂:
- 使用 Faker 生成器注册 Eloquent 工厂。
启动方法:
- 在启动时设置模型的连接解析器和事件分发器。
- 配置工厂名称和模型名称的推测方法。
- 注册模型保存时的私有检查逻辑。

详细代码可以在这里查看。

步子哥

Migrator.php 文件是 Flarum 框架中的迁移类，负责管理数据库迁移的执行。主要功能和方法包括：

属性:
- [imath:0]output: 用于输出消息的接口。
- [/imath:0]repository, [imath:0]connection, [/imath:0]files: 分别是迁移库、数据库连接和文件系统。
方法:
- run: 运行指定路径下的所有待迁移的迁移文件。
- runMigrationList: 执行一系列迁移文件。
- runUpMigrations: 执行一系列迁移文件的 "up" 方法。
- runDownMigrations: 执行一系列迁移文件的 "down" 方法。
- runUp: 运行单个迁移文件的 "up" 方法并记录。
- reset: 回滚所有已执行的迁移。
- runDown: 运行单个迁移文件的 "down" 方法并删除记录。
- runClosureMigration: 运行基于闭包的迁移。
- resolveAndRunClosureMigration: 解析并运行迁移，处理异常。
- getMigrationFiles: 获取指定路径下的所有迁移文件。
- resolve: 从文件中解析迁移实例。
- installFromSchema: 从模式转储初始化 Flarum 数据库。
- setOutput: 设置输出接口。
- note: 输出消息。
- getRepository: 获取迁移库实例。
- repositoryExists: 检查迁移库是否存在。

详细代码可以在这里查看。

步子哥

Collection.php 文件是 Flarum 框架中的一个自定义集合类，继承自 Laravel 的 BaseCollection。该类主要用于处理数据库模型的集合，具有以下主要功能：

命名空间: Flarum\Database\Eloquent
继承: 继承自 Illuminate\Database\Eloquent\Collection

主要方法包括：

loadAggregate:
- 作用: 解决在使用可见性作用域和急切加载 mentionedBy 的计数时产生的查询冲突问题。
- 实现: 通过在父查询中应用别名，防止 Laravel 自动为子查询生成别名。
- 示例查询问题见注释部分。
loadMissingRelation:
- 作用: 优化加载缺失关系的逻辑，避免不必要的属性变换器运行。
- 实现: 替换 ->whereNotNull() 为简单的 ->where(fn (mixed [imath:0]relation) => [/imath:0]relation !== null)，以避免变换器在 loadMissing() 调用完成前运行。

这个自定义集合类通过优化查询和关系加载，提升了性能并解决了一些特定场景下的冲突问题。详细代码可以在这里查看。

步子哥

以下是一些调整 Flarum 论坛字体大小的方法，从 18px 到 20px。我将提供几种方法，您可以根据自己的技术水平和对 Flarum 的熟悉程度选择最适合您的一种：

方法一：使用自定义 CSS (推荐，最灵活)

这是最推荐的方法，因为它允许您进行精细的控制，并且不会直接修改 Flarum 的核心文件。

找到自定义 CSS 的位置：
- 登录到您的 Flarum 管理面板。
- 导航到“外观” (Appearance) -> “自定义样式” (Custom Styles)。有些主题可能将此选项放在不同的位置，例如“主题设置”或“高级设置”中。

添加 CSS 代码：

将以下 CSS 代码添加到自定义样式区域：

    body {
      font-size: 20px; /* 全局字体大小 */
    }

    /* 如果你想更具体地控制不同区域的字体大小，可以使用以下代码 */
    .Post-body {
      font-size: 20px; /* 帖子内容字体大小 */
    }

    .DiscussionListItem-title {
      font-size: 20px; /* 讨论列表标题字体大小 */
    }

    .CommentPost .Post-body {
      font-size: 20px; /* 回复内容字体大小 */
    }

    /* 你可以根据需要添加更多选择器来控制其他元素的字体大小 */

解释：
- body { font-size: 20px; } 这条规则会设置整个论坛的默认字体大小为 20px。
- 后面的选择器（.Post-body, .DiscussionListItem-title 等）允许您更精确地控制特定元素的字体大小。您可以根据需要添加或修改这些选择器。
重要： 使用浏览器的开发者工具（通常按 F12 键打开）来检查您想要修改的元素的 CSS 类名。这样可以确保您使用正确的选择器。

保存更改：

保存您的自定义样式。刷新您的 Flarum 论坛，查看更改是否生效。

方法二：修改主题文件 (不推荐，风险较高)

这种方法涉及直接修改 Flarum 主题的 CSS 文件。 强烈建议您不要使用这种方法，除非您非常熟悉 CSS 和 Flarum 的主题结构。 直接修改主题文件可能会导致升级问题，并且容易出错。

找到主题文件：
- 使用 SSH 或 FTP 连接到您的 Flarum 服务器。
- 找到您的 Flarum 安装目录。
- 导航到 extensions/flarum-theme-THEME_NAME/less/ 目录 (或者 css 目录，具体取决于主题)。将 THEME_NAME 替换为您正在使用的主题的名称。例如，如果使用默认主题，路径可能是 extensions/flarum-theme-default/less/。
- 找到 theme.less 或 style.less 文件 (或者类似的文件，具体取决于主题)。
修改字体大小：
- 使用文本编辑器打开 theme.less 或 style.less 文件。
- 找到定义字体大小的 CSS 规则。这些规则可能使用 font-size 属性。
- 将字体大小从 18px 修改为 20px。
- 重要： 在修改文件之前，请务必备份该文件。
清除缓存：
- 修改文件后，您需要清除 Flarum 的缓存才能使更改生效。
- 在 Flarum 管理面板中，导航到“扩展” (Extensions)，找到您正在使用的主题，然后禁用并重新启用它。这通常会清除缓存。
- 如果上述方法不起作用，您可能需要手动清除缓存。您可以尝试删除 storage/cache 目录中的内容。

方法三：使用 Flarum 扩展 (如果存在)

有些 Flarum 扩展允许您自定义论坛的外观，包括字体大小。您可以搜索 Flarum 扩展市场，看看是否有这样的扩展可用。如果存在，使用扩展通常是最简单的方法。

注意事项：

备份： 在进行任何修改之前，请务必备份您的 Flarum 数据库和文件。
缓存： 修改 CSS 文件后，请务必清除 Flarum 的缓存，以确保更改生效。
浏览器开发者工具： 使用浏览器的开发者工具来检查元素的 CSS 类名，并查看更改是否生效。
主题兼容性： 某些主题可能具有自己的字体大小设置，这可能会覆盖您的自定义 CSS。在这种情况下，您可能需要修改主题的设置或使用更具体的 CSS 选择器。
响应式设计： 确保您的字体大小设置在不同的设备上看起来都不错。您可以使用媒体查询来根据屏幕大小调整字体大小。

步子哥

site.php : 这段代码是一个 PHP 文件的一部分，通常用于设置和配置 Flarum 论坛的站点。以下是对代码的详细解释：

首先，代码包含了一段注释，使用了 |-------------------------------------------------------------------------------| 这样的分隔符来组织内容。这段注释解释了代码的两个主要部分：加载自动加载器和配置站点。

在第一部分，代码通过 require __DIR__.'/vendor/autoload.php'; 加载了自动加载器。这个自动加载器是由 Composer（PHP 的包管理器）在安装依赖项后自动生成的。加载这个文件后，所有依赖项中的类都可以直接使用，而不需要显式地加载任何文件。这大大简化了代码的管理和依赖项的使用。

接下来是配置站点的部分。注释详细说明了 Flarum 站点的配置选项，包括几个重要的路径：

基础路径（base path）：这是 Flarum 的根目录，包含了重要的文件，如 config.php 和 extend.php。
公共路径（public path）：这是作为 Web 服务器文档根目录的目录。这个目录中的文件可以被公共互联网访问，通常存放 JavaScript 文件或 CSS 样式表等资源。
存储路径（storage path）：这是 Flarum 在运行时生成文件的存储位置，可能包括缓存、会话数据或其他临时文件。

最后，代码返回了一个通过这些路径配置好的 Flarum 站点实例。这个实例将被包含该脚本的其他代码使用，用于启动 Flarum 应用程序并处理 Web 请求。

总的来说，这段代码的主要功能是加载必要的依赖项并配置 Flarum 站点的路径，以便正确地启动和运行 Flarum 论坛。

步子哥

1. Flarum 使用标准的会话 Cookie

Flarum 是一个 PHP 构建的论坛系统，默认使用标准的 HTTP 会话 Cookie 来管理用户会话。这意味着用户登录后，Flarum 会通过服务器端生成一个会话标识符（Session ID），并将其存储在用户的浏览器 Cookie 中。

2. 前端 SPA（单页应用）的用户身份验证处理

Flarum 的前端是一个单页应用（SPA），通过与后端 API 的交互来实现身份验证。在前端发起登录请求（通常是向 /api/token 或 /login 之类的端点发送 POST 请求）时：

如果认证成功，后端会返回相应的 AccessToken（通常是一种 JWT 或类似的令牌）。
同时，后端会在响应中设置一个会话 Cookie。这些 Cookie 会自动附加到后续的 HTTP 请求中。

3. AccessToken 和 Cookie 的作用

AccessToken: 主要用于前端直接调用 API 时（例如：通过 JavaScript Fetch 请求或 Axios 请求）。前端应用可以将这个 AccessToken 存储在内存中或本地存储中，用于后续的身份验证。
Cookie: 是浏览器自动管理的，它会在同源请求时自动附加到 HTTP 请求头中（Cookie 字段）。Flarum 后端会通过这个 Cookie 来识别用户的会话。

4. 为什么会同时设置 Cookie 和返回 AccessToken？

这是因为 Flarum 的架构需要兼顾前端 SPA 和传统的会话管理：

Cookie 机制: 提供了标准化的会话管理，尤其是对于需要传统页面加载的场景（例如访问 / 或非 API 请求）。
AccessToken: 为前端 SPA 提供了一种灵活的、无状态的身份验证方式，便于前端直接通过 API 与后端交互。

5. 实际行为

当用户登录时，以下是可能的流程：

前端通过 POST /api/token（或类似端点）发送用户名和密码。
后端验证用户身份：
- 如果验证成功，后端会设置一个会话 Cookie（例如 flarum_session）。
- 后端还会在响应中返回一个 AccessToken，供前端手动管理 API 调用中的身份验证。
后续请求：
- 如果是前端通过 JavaScript 发起的 API 请求，可以使用 AccessToken（通常放在 Authorization: Bearer <AccessToken> 头中）。
- 如果是浏览器直接发起的请求（例如页面加载或资源请求），浏览器会自动附加 Cookie，后端通过会话 Cookie 验证用户身份。

6. 总结

Flarum 同时设置 Cookie 和返回 AccessToken 是为了兼容性和灵活性：

Cookie 是传统的会话管理方式，适用于浏览器自动处理的场景。
AccessToken 提供了前端 SPA 与后端交互的无状态身份验证方式。

这种双重机制确保了 Flarum 能够同时支持传统的浏览器行为和现代的前端单页应用需求。