xnx_custom_groups 自定义用户组示例

Xiuno BBS X 示例插件，演示如何通过插件创建自定义 gid 的用户组并注册插件权限项，作为开发者编写同类插件的参考实现。

功能特性

• 通过 install.php 创建 3 个自定义 gid 的用户组（gid=3、200、201）

• 通过 hook/admin_group_start.php 注册 2 个示例插件权限项

• 3 种语言资源（简中、繁中、英文）

• 卸载时安全清理：检测组内仍有用户时跳过删除，避免用户被孤立

• 幂等安装：重复安装时只更新基础字段，不覆盖管理员后期调整的权限

创建的用户组

gid=3 占用系统组 install.sql 中预留的空缺位（命中 gid 1-5 管理权限区间）；gid=200/201 避开 101-105 的等级用户组。

注册的权限项

通过 PermissionService::register() 注册 2 个权限键：

注册后自动出现在后台 → 用户组编辑 → 插件权限分组中，所有用户组（包括本插件创建的 3 个组）都会显示对应的勾选框。

安装与卸载

在后台 → 插件管理中安装/卸载，无需手动操作。

安装

• 调用 group_create() 创建 3 个用户组

• group_create() 内部自动调用 forum_access_padding($gid, TRUE)，使新组自动出现在所有版块的权限矩阵中

• 调用 group_list_cache_delete() 清缓存

• 写入 kv: xnx_custom_groups_installed 安装标记

卸载

• 遍历 3 个 gid，逐个安全检查

• 若组内仍有用户（db_count('user', ['gid' => $gid]) > 0），写入日志并跳过删除

• 空组调用 group_delete() 删除，内部自动清理 bbs_forum_access 关联

• 清理 kv: xnx_custom_groups_installed

自动继承的系统功能（无需额外代码）

本插件创建的用户组会自动出现在以下位置：

1. 版块编辑页权限矩阵：group_create() 调用 forum_access_padding() 自动填充 bbs_forum_access 表

2. 用户组列表与编辑页：$grouplist 读取 bbs_group 表所有组

3. 其他插件的权限设置：group_update.htm 遍历 PermissionService::getAllRegisteredKeys()，所有已注册的插件权限项都会显示在本插件创建的组的编辑页中

使用示例

权限检查（PHP）

if (!PermissionService::check('xnx_custom_groups_vip_feature', $uid)) {
    message(-1, '权限不足');
}
// 管理员组（gid=1,2）自动返回 true，无需特殊处理

将用户加入自定义组（PHP）

user_update($uid, array('gid' => 200));  // 设为 VIP 会员组

技术实现要点

• gid 选择：避开 0/1/2/4/5/6/7（系统组）、101-105（等级组），使用预留空缺 3 和扩展区间 200/201

• 幂等安装：已存在的组只 group_update 基础字段，不覆盖管理员后期调整的权限

• 运行时权限注册：PermissionService::register() 是静态注册（重启即丢失），通过 hook/admin_group_start.php 在每次进入后台用户组管理页时重新注册

• 卸载安全：检测组内用户数，非空时跳过删除并写日志

• 多语言 hook：3 个 lang_*_bbs.php hook 注册语言键，自动合并到全局 $lang 数组

文件结构

xnx_custom_groups/
├── conf.json                       # 插件配置
├── icon.png                        # 插件图标
├── install.php                     # 安装脚本（创建用户组）
├── uninstall.php                   # 卸载脚本（安全删除用户组）
└── hook/
    ├── admin_group_start.php       # 注册插件权限项
    ├── lang_zh_cn_bbs.php          # 简体中文语言包
    ├── lang_zh_tw_bbs.php          # 繁体中文语言包
    └── lang_en_us_bbs.php          # 英文语言包

版本信息

• 插件版本：1.0.0

• 兼容核心版本：Xiuno BBS X 1.1

• 作者：twelve