Webman自定义插件开发_PHP Webman封装可复用的功能组件【工具】-php教程-PHP中文网

webman插件分应用插件和基础插件两类：前者放plugin/目录、用php webman app-plugin:create创建、访问路径为/app/{标识}；后者走composer发布、代码在vendor/、配置自动合并至config/plugin/{vendor}/{name}/，二者目录结构、安装方式与配置机制完全不同。

webman自定义插件开发_php webman封装可复用的功能组件【工具】

webman插件分两类：应用插件 vs 基础插件，别混用

开发前先确认你要封装的是「独立模块」还是「通用能力」。前者是应用插件（如后台管理、钉钉通知），后者是基础插件（如加密工具、验证器）。两者目录结构、安装方式、配置加载机制完全不同。

应用插件放在 plugin/ 目录下，通过 php webman app-plugin:create demo 生成，访问路径为 /app/demo；基础插件则走 Composer 流程，发布到 Packagist，安装后配置自动合并进 config/plugin/{vendor}/{name}/，代码在 vendor/ 下。

误把基础插件当应用插件：会导致 config/plugin/ 配置不被识别，config('plugin.xxx') 返回 null
误把应用插件当基础插件发布：无法通过 composer require 安装，且路由、中间件不会自动注册
应用插件不能直接 composer dump-autoload 生效，必须重启服务；基础插件 reload 后需手动触发 php webman config:cache（如果用了配置缓存）

基础插件必须声明 `ext-openssl` 这类扩展依赖

很多工具类（比如 AES 加密、JWT 签名、SSL 请求）依赖 PHP 扩展。若插件用到了 openssl_encrypt 却没声明依赖，用户安装后运行直接报 Call to undefined function openssl_encrypt()，但错误堆栈里根本看不到你的插件名——它卡在 autoload 或构造函数里就崩了。

正确做法是在插件根目录的 composer.json 中明确写：

{
  "require": {
    "php": ">=7.4",
    "ext-openssl": "*"
  }
}

不声明 ext-* 依赖，composer install 不会报错，但运行时失败，排查成本高
PHP 版本约束也得写实，比如 webman_tool 要求 >=7.2，但你的 AES 插件若用了 openssl_cipher_iv_length()（PHP 7.4+），就得锁死 >=7.4
测试时务必在干净环境（Docker 或全新虚拟机）验证：docker run --rm -v $(pwd):/app -w /app php:8.1-cli composer install && php -r "echo extension_loaded('openssl') ? 'ok' : 'fail';"

`config/plugin/xxx/yyy/route.php` 的路由注册有陷阱

基础插件的 route.php 文件会被 webman 自动加载，但只在 Route::group() 或 Route::any() 等顶层调用才生效。如果你在里面写了 $router->get()（即用注入的 $router 实例），它不会注册成功——因为此时路由实例还没初始化完成，插件配置阶段只认静态注册语法。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

正确写法是返回一个数组，由 webman 内部统一注册：

return [
  'GET /api/v1/encrypt' => [App\Controller\EncryptController::class, 'index'],
  'POST /api/v1/decrypt' => [App\Controller\DecryptController::class, 'handle']
];

写 Route::get() 会静默失败，接口 404，日志里没有任何提示
路由前缀不会自动加插件名，/api/v1/encrypt 就是真实路径，要避免和主项目冲突
如果要用中间件，得在同目录的 middleware.php 里定义并绑定，不能在 route.php 里链式调用 ->middleware()

插件内读取配置必须用 `config('plugin.xxx.yyy.key')`

基础插件的配置文件（如 config/plugin/tinywan/encryption/app.php）会被合并进全局配置，但 key 是带命名空间的。直接写 config('app.debug') 拿到的是主项目的配置，不是你插件的。

所有插件配置都强制挂载在 plugin. 下，层级对应目录路径。例如：

config/plugin/tinywan/encryption/app.php → config('plugin.tinywan.encryption.app')
config/plugin/tinywan/encryption/database.php → config('plugin.tinywan.encryption.database')
不要尝试删掉 plugin. 前缀去“简化”，否则运行时拿不到值，且无任何 warning
配置值建议设默认 fallback，比如 config('plugin.tinywan.encryption.app.key', 'default-key')，避免空值引发后续逻辑异常

复杂点在于：插件配置可能被主项目覆盖。比如主项目 config/plugin/tinywan/encryption/app.php 里写了 'key' => 'prod-key'，那你就拿不到插件自带的默认值了——这个覆盖行为是设计使然，但容易被忽略。