Flarum Approval 扩展演进史:从 CHANGELOG 到源码的版本解读与核心机制剖析

原创2026-10-10 23:32:481,444 阅读
文章标签:后端前端

Flarum Approval 扩展演进史:从 CHANGELOG 到源码的版本解读与核心机制剖析

导读

本文以 extensions/approval/CHANGELOG.md 为主干,逐版本还原 Flarum 官方审核扩展 Approval(flarum/approval)从早期 beta 到 1.2.0 的开发演进脉络,并结合当前仓库源码,深入剖析其"新内容标记待审、未审内容私有化、审核通过后计数联动刷新"的核心实现。读完本文,你将理解该扩展的每一项 CHANGELOG 变更背后的真实代码逻辑,掌握其数据模型、权限体系、事件链路与前端交互的完整工作原理,并能以此为参考在自己的 Flarum 扩展中正确使用 extenders、模型可见性与事件机制。

一、扩展定位:这是什么扩展

Approval 是 Flarum 官方维护的审核类扩展,其 composer.json 中的描述一句话概括了它的使命:"Make discussions and posts require moderator approval."(让话题与回复需要版主审核)。它被归类在 feature 管理类别(CHANGELOG 中 beta.16 正是把管理后台类别从 moderation 调整为 feature 的提交),强依赖 flarum/core 与 flarum/flags(待审内容以 Flag 形式进入举报/审核队列),并把 flarum/audit 声明为可选依赖、flarum/tags 用作测试依赖。

从架构上看,这个扩展非常轻量:全部后端逻辑集中在 src/ 下的 4 个 Listener、1 个 Event、1 个 API 字段扩展和 3 个访问控制类中,通过 extend.php 中一套现代 extenders 声明式地接入核心框架,这本身就是 CHANGELOG 反复强调的"从 deprecated core events 迁移到 extenders"的直接成果。

二、版本演进脉络:CHANGELOG 逐条解读

CHANGELOG 记录了从 0.1.0-beta.13 到 1.2.0 的完整开发史。表面看它只有寥寥数行"Changed/Fixed"条目,但每一条都能在当前源码中找到对应痕迹。按时间正序梳理如下。

2.1 0.1.0-beta.13:弃用核心事件,全面改用 extenders

Changed: Stop using deprecated core events, use extenders instead.

这是该扩展走向现代 Flarum 架构的第一步。此前版本直接监听核心事件,而新架构要求通过 extend.php 中的 Extend\Event、Extend\Policy、Extend\ModelVisibility 等 extenders 声明式接入。今天你在 extend.php 中看到的完整声明清单(Model 默认值与类型转换、ApiResource 字段、事件订阅、策略、可见性、私有性、条件扩展),正是这条历史决策的最终形态。

2.2 0.1.0-beta.14:Mithril 2 迁移与依赖清理

Changed: Updated mithril to version 2; Load language strings correctly on en-/disable; Updated JS dependencies Removed: Removed AssertPermissionTrait (#19)

Mithril 2 迁移涉及全部前端组件;"语言字符串在启用/禁用时正确加载"对应 locale/en.yml 与 Extend\Locales(__DIR__.'/locale') 的配合;移除 AssertPermissionTrait 意味着权限断言改用 $actor->assertCan() / $actor->can() 的内置能力,这一模式在 ApproveContent.php 中仍清晰可见。

2.3 0.1.0-beta.15:新后台区域与最新 extenders

Changed: Updated composer.json and admin javascript for new admin area; Updated extend.php with latest extenders.

对应管理后台前端在 js/src/admin/extend.tsx 中通过 Extend.Admin().permission(...) 注册三个权限项,并指定图标(fas fa-check)、所属分组(start/reply/moderate)与显示优先级(95/95/65)。

2.4 0.1.0-beta.16:类别调整、locale 迁移与计数修复

Changed: Updated admin category from moderation to feature; Moved locale files from translation pack to extension Fixed: Comment and discussion count not updated after post approval (#16)

  • 类别调整:composer.json 的 extra.flarum-extension.category 现为 "feature";
  • locale 迁移:翻译从翻译包迁入扩展自身目录,locale/en.yml 即为此迁移的产物,涵盖后台权限标签、前台待审徽章、帖子控制按钮以及审计日志文案;
  • 计数修复(PR #16):这是最有价值的修复。审核通过后,帖子计数与话题计数必须联动更新,其实现位于 UpdateDiscussionAfterPostApproval.php:刷新话题的 comment_count 与最后回复信息;若被审核的是首帖($post->number === 1),则同时将话题置为已审核并刷新作者的话题计数,再刷新帖子作者与话题作者的回复计数。

2.5 1.0.0:Flarum 1.0 兼容、TagPolicy 简化与私有性修复

Changed: Compatibility with Flarum v1.0.0; Simplified TagPolicy Fixed: Unpredictable behaviour existed with discussions marked is_private (PR #26)

  • Flarum v1.0 兼容:依赖约束随之更新(当前仓库面向 Flarum 2.x,flarum/core: ^2.0.0);
  • 简化 TagPolicy:当前的 TagPolicy.php 只有区区 12 行,addToDiscussion 能力直接委托给 discussion.startWithoutApproval 权限——即"谁能免审发帖,谁就能把话题放进该标签",这就是简化后的最终形态;
  • is_private 行为修复(PR #26):修复前,被标记为私有的待审内容行为不可预期;修复后,私有性与审核状态由 UnapproveNewContent.php 的 markUnapprovedContentAsPrivate 统一接管(is_approved 为假即视为私有),可见性则由 ScopePrivateDiscussionVisibility.php 与 ScopePrivatePostVisibility.php 两个 scope 以 orWhere 方式精确放行。

2.6 1.1.0 / 1.2.0:稳定期

No changes.

这两个版本仅标记兼容性稳定,无行为变更。截至当前仓库,扩展仍保持这一稳定状态,前端继续使用 Mithril 2 生态,后端沿用 v1.0.0 定型的架构。

三、核心机制源码级剖析

CHANGELOG 提到的修复与重构,最终沉淀为如下几条关键调用链。理解它们,就能理解整个扩展。

3.1 新内容自动标记待审(UnapproveNewContent)

新帖保存(Post\Event\Saving)时,UnapproveNewContent.php 按 first_post_id 是否为 null 区分"发新话题"与"回复"两种能力:

$ability = $post->discussion->first_post_id === null ? 'startWithoutApproval' : 'replyWithoutApproval';

if ($event->actor->can($ability, $post->discussion)) {
    // 有能力:默认 approved(若未显式指定)
} else {
    $post->is_approved = false;  // 无能力:标记待审
}

未获权限的内容还会在 afterSave 中做两件事:若为首帖,把所属话题也置为待审;并创建一条 type = 'approval' 的 Flag(Flag.php 关联的 flags 表),使待审内容进入审核队列。这与 composer.json 对 flarum/flags 的强依赖一致。

3.2 未审内容私有化(ModelPrivate)

待审内容虽然写入数据库,但默认必须对公众不可见。extend.php 通过 Extend\ModelPrivate 把 Discussion 与 CommentPost 的私有判定委托给 markUnapprovedContentAsPrivate:

public static function markUnapprovedContentAsPrivate(Discussion|CommentPost $instance): ?bool
{
    if (! $instance->is_approved) {
        return true;   // 未审核 → 私有
    }
    return null;       // 已审核 → 交给其他检查器
}

这就是 CHANGELOG 1.0.0 中"不可预期 is_private 行为"修复后的确定性规则:审核状态是私有性的唯一依据。

3.3 可见性精确放行(Scope 实现)

私有内容的可见性由两个 scope 控制,均采用"orWhere 追加可见子集"而非"收窄可见集合"的写法(源码注释明确强调这一点,否则会误伤正常可见内容):

  • 讨论可见条件:ScopePrivateDiscussionVisibility.php 中,未审核讨论对"拥有 discussion.approvePosts 权限的用户"以及"讨论作者本人"可见;
  • 帖子可见条件:ScopePrivatePostVisibility.php 更进一步,通过 discussionWhereCanApprovePosts 子查询,支持"按讨论维度授权"的场景——例如 tags 扩展把 approvePosts 能力细化为按标签授权,此时只有能在该讨论所在标签下审核的人才能看到对应待审帖子。

extend.php 中对应的声明为:

(new Extend\ModelVisibility(Post::class))
    ->scope(Access\ScopePrivatePostVisibility::class, 'viewPrivate'),
(new Extend\ModelVisibility(Discussion::class))
    ->scope(Access\ScopePrivateDiscussionVisibility::class, 'viewPrivate'),

3.4 审核通过链路(ApproveContent → PostWasApproved → 联动刷新)

审核动作经 ApproveContent.php 处理,存在两条入口:

  1. 显式审核:请求属性携带 isApproved,先 assertCan('approve', $post) 校验,然后置 is_approved = true 并抛出 PostWasApproved 事件;
  2. 静默审核:请求携带 isHidden 且操作者具备 approve 能力时,隐藏操作会"顺带"静默通过审核——这与 ApprovePostsTest.php 中 hiding_post_silently_approves_it 测试完全对应。

PostWasApproved(见 PostWasApproved.php)是一个携带 Post 与操作者 User 的领域事件,由 UpdateDiscussionAfterPostApproval.php 监听,完成 CHANGELOG beta.16 修复的计数刷新:刷新话题回复数与最后回复、审核首帖时联动通过整个话题并刷新作者话题计数、刷新相关用户回复计数。

3.5 标签元数据联动(UpdateTagMetadataAfterApproval)

由于待审讨论是私有的,flarum/tags 会跳过它们,导致标签的 discussion_count 与 last_posted_discussion_id 停留在审核前的陈旧状态。UpdateTagMetadataAfterApproval.php 在 PostWasApproved 后补偿刷新:首帖通过时 discussion_count++,并总是刷新该标签的最后回复讨论。extend.php 用 Extend\Conditional->whenExtensionEnabled('flarum-tags', ...) 包裹这一监听,保持 tags 扩展对审核机制"无感知"的松耦合设计——这一点在源码注释中写得非常直白。

3.6 前端交互

前端(js/src/forum/index.js)承担三件事:

  • 待审徽章:未审核讨论在列表项与讨论页挂上 awaitingApproval 徽章(fas fa-gavel 图标),并通过 DiscussionListItem--unapproved / Post--unapproved 类名触发淡化样式;
  • 审核按钮:PostControls 的 destructiveControls 中,当帖子未审核且当前用户 canApprove 时插入 Approve 按钮,点击后 save({ isApproved: true }),若审核的是首帖则同步推送讨论的 isApproved 属性;
  • 审核理由显示:覆写 flagReason,把 type === 'approval' 的 Flag 显示为"Awaiting approval"。

样式细节值得一提:less/forum.less 特意将淡化样式施加到具体元素而非 <article> 祖先,并在注释中解释了原因——对祖先施加 opacity 会创建独立层叠上下文,使帖子自带的用户卡片、下拉菜单等浮层无法逃脱,导致控件无法点击(引用了 #4505 等历史 issue 的同源根因)。

3.7 审计日志集成

当 flarum/audit 启用时,extend.php 中的 Extend\Conditional 注册两组审计动作:post.approved(记录 discussion_id 与 post_id)和 discussion.approved(仅当审核的是首帖时记录)。相关文案定义在 locale/en.yml 的 flarum-audit 命名空间下("Approved {postuser}'s {post} in {discussion}"),由 AuditTest.php 通过 assertLogExists 验证。这也解释了 composer.json 为何把 flarum/audit 声明为可选依赖。

四、数据模型与权限设计

4.1 数据列与默认值

扩展通过两个迁移在既有表上追加布尔列,默认值为 1(已审核),保证历史数据默认可见:

extend.php 中 Extend\Model(Discussion::class)->default('is_approved', true)->cast('is_approved', 'bool')(Post 同理)进一步在模型层保证新实例默认已审核、并按布尔类型读取。API 层面,extend.php 为讨论资源暴露 isApproved 布尔字段,为帖子资源通过 PostResourceFields.php 暴露 isApproved(仅 approve 权限者可写)与 canApprove(只读,判断当前用户能否在所在讨论中审核)。

4.2 权限体系

三个权限构成完整闭环,种子数据见 2017_07_22_000000_add_default_permissions.php:

权限键 默认授予 作用
discussion.startWithoutApproval 成员组(MEMBER_ID) 发新话题免审核
discussion.replyWithoutApproval 成员组(MEMBER_ID) 回复免审核
discussion.approvePosts 版主组(MODERATOR_ID) 审核帖子

后台权限页由 js/src/admin/extend.tsx 注册三项,并配置前置依赖:js/src/admin/index.ts 通过 getRequiredPermissions 声明 startWithoutApproval 依赖 startDiscussion、replyWithoutApproval 依赖 discussion.reply,确保未授予基础发帖权限时不会出现"免审"权限悬空。

五、测试覆盖:集成测试如何验证 CHANGELOG 承诺

仓库的 tests/integration/api 与 tests/integration 下的测试直接对应 CHANGELOG 的每条行为承诺:

  • CreatePostsTest.php:数据驱动验证"发新话题/回复时,持有对应免审权限则 is_approved = 1,否则为 0"(管理员、授权用户、无权限用户四组用例);
  • ApprovePostsTest.php:验证 PATCH /api/posts/{id} 携带 isApproved: true 可审核(200)、无权限者被拒(403)、以及"隐藏帖子即静默通过审核";
  • ListDiscussionsTest.php 与 ListPostsTest.php:分别验证讨论列表与帖子流中,审核者/作者可见未审内容,其他用户只见已审内容——这正是 1.0.0 PR #26 修复后确定性可见性规则的回归测试;
  • TagMetadataTest.php:验证审核首帖后,标签的 discussion_count 从 0 变为 1、last_posted_discussion_id 正确指向该讨论;
  • AuditTest.php:验证 post.approved 与 discussion.approved 审计条目生成。

测试通过 composer.json 中的 composer test:unit / composer test:integration(分别以 tests/phpunit.unit.xml、tests/phpunit.integration.xml 为配置)运行,集成测试前需先执行一次 composer test:setup 初始化数据库。

六、结语:一条 CHANGELOG 背后的工程价值

回看这份只有十余条记录的 CHANGELOG,它实际上浓缩了一个成熟扩展的三次关键跃迁:架构现代化(beta.13–15:从裸事件监听迁移到 extenders、Mithril 2、新后台体系)、行为正确性(beta.16 的计数修复、1.0.0 的 is_private 确定性修复)、生态协同(locale 内迁、tags/audit 条件集成)。当你阅读 extend.php 时看到的每一条声明,几乎都能在这份 CHANGELOG 中找到它的诞生时刻——这正是开源项目"变更日志即设计文档"的绝佳范例,也是 Flarum 审核类功能落地时值得逐行研读的参考实现。

登录后查看全文
framework