# 开源webman框架插件composer **Repository Path**: umaos/webman ## Basic Information - **Project Name**: 开源webman框架插件composer - **Description**: 开源webman框架插件composer - **Primary Language**: PHP - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-03 - **Last Updated**: 2026-10-24 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # umaos/webman Webman 通用业务扩展库，封装 UMaos 平台的多端（index 前台 / admin 管理 / system 中台）通用能力：**控制器解析与权限节点生成、统一响应输出、登录鉴权（RBAC）、数据模型、构建/随机/字符串/HTTP 等工具**。业务项目通过 Composer 引入即可复用，支持标准 app 结构与 plugin 插件结构。 - 命名空间：`umaos\webman\` - 依赖：PHP >= 8.1、webman-framework ^2、think-orm ^2 ## 特性 - **多端统一鉴权**：Auth 类按 module 区分三端用户，统一登录/退出/权限校验，session 键 `{module}_login_user` - **RBAC 权限体系**：用户 → 分组 → 规则节点（dir/menu/file 三级），超管规则 `*` - **权限节点自动生成**：ControllerScanner 扫描控制器目录 + Controller::getControllerInfo 反射解析类/方法注释与 noNeedLogin/noNeedRight，自动生成权限树 - **统一响应**：Show 类按请求形态自动返回 JSON 或提示模板页（code: 0 成功 / 1 失败 / 2 警告 / 3 未登录） - **视图布局渲染**：Layout 类支持公共布局包裹，模板根目录可配置 - **工具集**：树构建、查询条件构建、随机串/UUID、命名转换、HTTP 请求、文件操作 ## 安装 ```bash composer require umaos/webman ``` 若安装 dev 版本（使用未打 tag 的最新提交），需在项目 `composer.json` 中允许不稳定版本： ```json { "minimum-stability": "dev", "prefer-stable": true } ``` ## 目录结构 ``` umaos/webman/ ├── public/ # 静态资源（前端库/样式/图片，安装时自动部署） │ ├── axios.min.js │ ├── pinia.iife.js │ ├── umaos.css │ ├── wallpaper.jpg │ ├── element-plus/ # Element Plus 组件库资源 │ ├── icons-vue/ # 图标库资源 │ └── vue/ # Vue 运行时 ├── src/ │ ├── Controller.php # 控制器基类：反射解析 + 权限节点生成 │ ├── Install.php # Webman 基础插件安装类（部署独立配置到主项目） │ ├── config/plugin/ # 基础插件独立配置（安装时自动部署到主项目 config/plugin/） │ │ └── umaos/webman/ # 插件主配置 + 静态资源路由 │ │ ├── app.php # enable/debug/version │ │ └── route.php # 静态资源路由（/plugin/umaos/ → 包内 public/） │ ├── helper/ # 工具类 │ │ ├── Builder.php # 树构建 buildTree / 查询条件构建 buildWhere │ │ ├── Files.php # 文件操作（递归建目录等） │ │ ├── Http.php # cURL 同步/异步请求、文件推送 │ │ ├── Layout.php # 视图布局渲染（模板根可配置） │ │ ├── Random.php # 随机串 / UUID │ │ ├── Show.php # 统一响应输出（JSON / 提示模板） │ │ └── Str.php # 命名转换（camel/snake/pascal） │ ├── library/ │ │ ├── Auth.php # 多端登录鉴权（登录/退出/取用户/权限校验） │ │ └── ControllerScanner.php # 控制器目录扫描 │ ├── middleware/ │ │ └── Worker.php # 全局鉴权中间件 │ ├── model/ # ThinkORM 模型（对应 fa_ 前缀表） │ │ ├── User.php # fa_index_user 前台用户 │ │ ├── Admin.php # fa_admin_user 管理员 │ │ ├── System.php # fa_system_user 系统用户 │ │ ├── AuthGroup.php # fa_auth_group 权限分组 │ │ └── AuthRule.php # fa_auth_rule 权限规则 │ └── traits/ # 预留控制器特性 │ ├── Backend.php # 管理端 │ ├── Frontend.php # 前台 │ └── Sysend.php # 中台 ├── composer.json └── README.md ``` ## 基础插件（webman 官方规范） 本包是 **webman 基础插件**（通用组件，代码位于 vendor，`composer` 安装），遵循官方基础插件规范（workerman.net/doc/webman/plugin/base.html）： - **独立配置**：插件配置存放于主项目 `config/plugin/umaos/webman/`，由包内 `Install` 类在 composer 安装/更新时**自动部署**（卸载时自动清理），webman 启动时自动识别合并，访问方式 `config('plugin.umaos.webman.app.xxx')` - **安装钩子**：`src/Install.php` 定义 `WEBMAN_PLUGIN` 常量，webman 框架的 `support\Plugin` 在 composer 安装/更新时自动调用 `install()/update()` - **静态资源走 Route**：`public/` 位于包内 vendor 目录，**无需复制、无需 public_path 配置**。仿照 `webman/push` 等官方基础插件，插件专属 URL 空间使用 `/plugin/{插件名}/`：`route.php` 动态扫描包内 public，为每个静态文件注册具体路径路由 `/plugin/umaos/{相对路径}`，返回文件响应（自动 Content-Type / 304 缓存），具体路径注册不与控制器路由（`/umaos/`）冲突 - 与项目内 umaos 业务应用（webman 官方多应用结构 `app/{index,admin,system}`）相互独立，互不干扰；公共模板由本包默认视图提供（可通过 `config('umaos.template_dir')` 自定义） 部署的配置文件（主项目 `config/plugin/` 下）： ``` config/plugin/ └── umaos/ └── webman/ ├── app.php # 基础插件独立配置（enable/debug/version） └── route.php # 静态资源路由（/plugin/umaos/ → 包内 public/） ``` 静态资源访问示例：`/plugin/umaos/vue/vue.global.prod.js` → 路由 → `vendor/umaos/webman/public/vue/vue.global.prod.js` 部署的配置文件（主项目 `config/plugin/` 下）： ``` config/plugin/ └── umaos/ └── webman/ ├── app.php # 基础插件独立配置（enable/debug/version） ├── autoload.php # 助手函数自动加载（webman 插件 autoload 机制） └── route.php # 静态资源路由（/plugin/umaos/ → 包内 public/） ``` ### 全局助手函数 本包通过 **webman 插件 autoload 机制**（而非 composer `autoload.files`）提供全局助手函数： - 由 `Install` 类部署 `config/plugin/umaos/webman/autoload.php`，其 `files` 声明 `vendor/umaos/webman/src/helpers.php` - webman 启动时（`support\bootstrap`）自动 `include_once` 该文件，所有助手函数即刻全局可用，无需手动引入 - 每个函数以 `function_exists()` 包裹，避免与框架或其他包重复定义 可用的全局助手函数： | 函数 | 说明 | | --- | --- | | `pre($data)` | 调试输出（print_r + 换行） | | `buildWhere($custom, $field)` | 构建 ThinkORM 查询条件闭包（like/in/between/findinset 等） | | `getControllerInfo($controller)` | 反射解析控制器，生成权限节点列表 | | `buildTree($data, $pid)` | 扁平数组转树形结构 | | `makePathLevelArr($path)` | 路径拆分为逐级层级数组 | | `umaos_init()` | 初始化请求鉴权上下文（module/auth/user/rule） | | `umaos_access()` | 校验当前请求访问权限，拦截返回响应 | | `show($code, $msg, $data, $tpl)` | 统一操作返回（JSON 或提示页面） | | `layout_view($tpl, $vars, $layoutOpt)` | 通用布局渲染（基于本包 `helper\Layout`） | | `addDir($dir)` | 递归创建目录 | | `viewPath($template, $vars, $app, $plugin)` | 解析并缓存模板路径（布局合并） | | `success($msg, $data, $tpl)` / `error(...)` / `warn(...)` / `login(...)` | 按状态码统一返回（0/1/2/3） | | `camelToSnake($str)` / `snakeToCamel($str)` / `snakeToPascal($str)` | 命名风格转换 | > umaos 业务应用（webman 官方多应用 `app/{index,admin,system}`）已切换为本包助手函数（原应用插件 `plugin/umaos` 已迁移并移除）。 ## 快速开始 ### 1. 注册全局鉴权中间件 在项目 `config/middleware.php` 的全局中间件中加入： ```php return [ '' => [ \umaos\webman\middleware\Worker::class, // ...其他中间件 ], ]; ``` 中间件会依次执行：记录 `lang` 到 session → `Auth::init()` 初始化请求上下文（module/auth/user/rule）→ `Auth::access()` 权限校验 → 放行控制器。 ### 2. 控制器继承与权限节点 控制器类注释作为菜单标题、方法注释作为节点标题，默认属性控制免登录/免授权： ```php user) { return Auth::access(); } return \umaos\webman\helper\Show::success('欢迎回来', request()->user); } } ``` 权限节点生成流程：`ControllerScanner::getLists()` 汇总全部控制器 → `Controller::getControllerInfo()` 反射解析 → 生成 dir/menu/file 三级规则写入 `fa_auth_rule`。 ### 3. 统一响应 ```php use umaos\webman\helper\Show; // JSON（ajax 请求自动返回 JSON；浏览器直开自动渲染提示模板） return Show::success('操作成功', ['id' => 1]); return Show::error('操作失败'); return Show::warn('请注意'); return Show::login('请先登录'); // code:3，前端据此跳转登录页 // 强制 JSON / 强制模板 return Show::success('成功', [], false); // 强制 JSON return Show::error('失败', [], true); // 强制渲染 error 模板 ``` 响应结构：`{code, msg, data, auth}`；渲染模板时额外附带 `name`（页面标题）。 ### 4. 登录鉴权 ```php use umaos\webman\library\Auth; // 登录（按当前 module 查对应用户表，md5(md5(pwd)+salt) 校验） return Auth::setLogin($username, $password); // 退出 return Auth::setOut(); // 获取当前登录用户与规则（返回 ['user' => [], 'rule' => []]） $login = Auth::getLogin(); // 权限校验（中间件内自动调用；返回 false 表示放行） if ($block = Auth::access()) { return $block; } ``` 登录成功时自动写入 session（键 `{module}_login_user` = 用户 ID），响应中的用户信息已剔除 `password`/`salt` 敏感字段。 ### 5. 数据模型 三端用户模型均提供 `getInfo` / `getGroup` / `getRules` 静态方法： ```php use umaos\webman\model\User; $user = User::getInfo($userId); // 已剔除敏感字段 $groups = User::getGroup($userId); // 分组 ID 数组 $rules = User::getRules($userId); // 权限规则集合（超管为 ['*']） ``` ### 6. 工具类 ```php use umaos\webman\helper\Builder; use umaos\webman\helper\Random; use umaos\webman\helper\Str; use umaos\webman\helper\Http; // 树构建 $tree = Builder::buildTree($flatList); // 列表需含 id/pid // 查询条件构建（ThinkORM where 闭包） $where = Builder::buildWhere( ['status' => 1, 'name' => 'admin'], ['status' => '=', 'name' => 'LIKE'] ); $list = Model::where($where)->select(); // 随机串 Random::alnum(6); // 数字+字母 Random::alpha(6); // 纯字母 Random::numeric(4); // 纯数字 Random::uuid(); // UUID v4 // 命名转换 Str::camelToSnake('AdminUser'); // admin_user Str::snakeToCamel('admin_user'); // adminUser Str::snakeToPascal('admin_user'); // AdminUser // HTTP 请求 Http::get($url, ['a' => 1]); Http::post($url, ['b' => 2]); Http::sendAsyncRequest($url, $data); // 异步，不等待响应 Http::sendToBrowser($filePath); // 推送文件到浏览器 ``` ## 模板路径配置 提示模板（tip/error/login）与布局模板（layout）的查找规则： - **默认（包内自带视图）**：直接使用包内默认视图 `vendor/umaos/webman/src/view`，无需任何配置 - **自定义视图**：将包内 `src/view` 目录复制到项目中（如 `app/umaos/view`），通过**基础插件配置** `config/plugin/umaos/webman/app.php` 指定模板根： ```php '/app/umaos/view', ]; ``` 模板目录约定： ``` {template_dir}/ ├── tip/ # 成功/警告提示页（success.html / warn.html） ├── error/ # 失败提示页，按模块分文件（{module}.html） ├── login/ # 未登录提示页，按模块分文件（{module}.html） └── layout/ # 公共布局，按应用分文件（{module}.html，{@body} 为内容占位符） ``` ## 版本记录 | commit | 内容 | | --- | --- | | 92ea284 | 初始版本 | | b25158f | 迁移 plugin/umaos 可复用能力并修复安全漏洞（密码/盐泄露、登录态校验） | | 74ac8c0 | 类名/方法名/变量名统一为 PSR 命名规范 | | c83b1cd | Show/Layout 模板路径改为相对路径（适配 webman view_path） | | ec57be9 | Show/Layout 支持 `config('umaos.template_dir')` 配置公共模板根，适配插件视图目录 | | 最新 | 为全部源码补充完整 PHPDoc 注释 | | 最新 | 新增全局助手函数（src/helpers.php），通过 webman 插件 autoload 机制加载，无需 composer autoload.files；应用插件已切换使用 | | 最新 | 适配 webman 官方多应用结构（app/{应用名}/controller），umaos_init/getControllerInfo 通用解析模块与权限路径（兼容多应用/主项目/插件），模板路径改 config('umaos.template_dir') 驱动，Layout 布局名模块优先 | ## 许可证 MIT