本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：8月13日备份/sosite-plugin-dev/plugin-system.md。

SoSite 插件系统介绍

适用版本：SoSite V5.0.0（PHP 8.2 / MySQL 5.7-8.0，自研 MVC，零 Composer 依赖）

统计日期：2026-08-09（与当前源码逐行核对）

关联文档：本目录 SKILL.md（开发规范主入口）、references/01-plugin-structure.md（结构规范）、references/02-hooks-catalog.md（hooks 速查）

一、插件系统架构

1.1 核心设计

1.2 加载流程（每次请求）

index.php / admin 入口
  → app/init.php: $GLOBALS['__view'] = new TemplateCompiler()
  → \app\Helpers\Plugin::init()          # 读缓存（无则扫描目录建缓存）
  → Plugin::hook('init_after')           # 初始化钩子
  → 路由注册: Plugin::hook('route_register' | 'admin_route_register')
  → dispatch: Plugin::hook('route_before_dispatch') → 控制器 → Plugin::hook('route_after_dispatch')

1.3 Hook 执行机制（Plugin::hook($name, $params)）

foreach (已启用的插件 as $config) {
    if ($config['hooks'][$name] 存在) {
        $hookFile = plugins/{dir}/ + 相对路径;
        // 路径安全：realpath 校验必须在插件目录内（防穿越），违规跳过
        include $hookFile;              // extract($params) 注入变量
        // 异常被 try/catch 捕获，单钩子失败不影响页面
    }
}

• 仅启用（plugin.json activated: true）的插件参与
• 参数经 extract(EXTR_SKIP | EXTR_REFS) 注入（&$data 引用型参数可回写）
• 钩子文件内可访问调用点作用域变量（如 $router、$view）
• 单个钩子抛异常只 error_log，不影响页面继续

二、插件生命周期

插件类约定（可选）：

namespace Plugin\Xxx;
class Plugin {
    public static function activate(): bool   { return true; }
    public static function deactivate(): bool { return true; }
    public static function uninstall(): void  {}
}

三、核心 Hook 总表（21 个，源码逐行核对）

触发文件 = 调用 Plugin::hook('name', ...) 的位置。

3.1 生命周期与全局

3.2 路由与导航

3.3 页面注入

3.4 用户行为

3.5 内容行为

四、插件 Hook 注册分布（14 个插件）

[启用] = plugin.json activated: true；[停用] = 注册但未启用（钩子不执行）。

汇总：14 个插件、11 启用 / 3 停用（content_review、invite、qa）；插件共注册 18 个不同 hook 名。

五、Hook 使用统计（注册次数）

六、插件系统 API（app\Helpers\Plugin）

Plugin::init();                      // 加载插件（缓存优先）
Plugin::hook($name, $params);        // 触发钩子
Plugin::getPlugins();                // 全部插件配置数组
Plugin::getPlugin($name);            // 单个插件配置
Plugin::isActivated($name);          // 是否启用
Plugin::activate($name);             // 启用（写 plugin.json + 调 Plugin.php::activate + 缓存）
Plugin::deactivate($name);           // 禁用
Plugin::updateConfig($name, $data);  // 更新白名单字段（name/version/author/description/activated/hooks）
Plugin::refresh();                   // 重建缓存（改 plugin.json 后必调）
Plugin::uninstall($name);            // 卸载（调 Plugin.php::uninstall + 移除注册）

后台入口：/admin/plugins（列表/启用/禁用/编辑配置/卸载），由 app/Controllers/Admin/PluginController 驱动。

七、已知坑与注意点（本系统特有）

1. nav_user_menu_items 历史无触发点：插件注册了该钩子但核心长期无 Plugin::hook('nav_user_menu_items') 调用（用户菜单入口不显示）；2026-08-09 已在 app/Views/layouts/main.php 移动端用户下拉菜单补触发点。若仍不生效，检查核心布局是否有该调用。
2. 同一 hook 多处触发（nav_plugin_links 两处、home_sidebar_bottom 两处、announcements_display 两处）：hook 文件会被 include 多次，输出会重复——用静态变量守卫或把只输出一次的逻辑放 init_after。
3. auth_register_before 传错约定：必须写 $GLOBALS['auth_register_error']，框架 hook 后读取非空即拦截注册。
4. 钩子内禁止 exit/die：会终止整页；抛异常会被捕获。
5. 视图对象可能为 null：hook 内用 $view = $GLOBALS['__view'] ?? null; 并兜底（icon 不可用时用 emoji/纯文本）。
6. PDO 两条铁律（全局 ATTR_EMULATE_PREPARES=false）：同一命名占位符不能复用（HY093）；SHOW 语句不能有占位符（1064，$conn->quote() 内联）。
7. 插件资源引用：直接 /plugins/{dir}/assets/...，勿用 asset()（会解析到 assets/plugins/ 发布目录，双份漂移）。
8. plugins_cache.php 是运行时产物：上传插件目录时不要覆盖它（含服务器上的启停配置），改 plugin.json 后 Plugin::refresh()。

八、配套文档索引