Flarum Approval 扩展演进史:从 CHANGELOG 到源码的版本解读与核心机制剖析
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 处理,存在两条入口:
- 显式审核:请求属性携带
isApproved,先assertCan('approve', $post)校验,然后置is_approved = true并抛出PostWasApproved事件; - 静默审核:请求携带
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(已审核),保证历史数据默认可见:
- 2015_09_21_011527_add_is_approved_to_discussions.php:
discussions.is_approved(boolean,default 1) - 2015_09_21_011706_add_is_approved_to_posts.php:
posts.is_approved(boolean,default 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 审核类功能落地时值得逐行研读的参考实现。