Composer在Webman中的使用实战指南

Webman项目必须遵循的Composer使用规范

在Webman项目里使用Composer，问题从来不是“能不能用”，而是“必须按它的规矩来”。一步走错，Class 'WebmanApp' not found、路由不加载、插件不生效，这些头疼的问题全都会找上门，根源往往就是没跟上Webman独特的Composer节奏。

为什么 composer create-project webman/webman 会失败或装错

直接运行composer create-project webman/webman，大概率会碰壁。这是因为官方的webman/webman仓库本质上是一个空骨架，它既没有提供composer.json入口，也没有打包好的dist发行版。Composer执行这个命令时，要么直接报错Could not find package webman/webman，要么退而求其次去拉取dev-master分支——后者意味着不稳定、缺少启动逻辑，并且没有正确的自动加载配置。

• Webman框架的正式发布形态，是GitHub Releases页面上提供的webman-x.x.x.zip文件（注意，不是Source code源码包）。
• 解压这个zip包后，你会得到一个完整的、可直接运行的环境，里面自带了正确的composer.json、核心启动文件start.php以及配置好的自动加载映射。
• 同样，composer require webman/webman这个命令也请避开。它安装的只是一个组件库，并非框架主体，装了之后你会发现连start.php这个入口文件都没有。

安装依赖时必须加 -W 参数

这是一个关键步骤。Webman出于安全考虑，默认禁用了部分PHP函数（例如exec、shell_exec）。问题在于，一些Composer包（比如illuminate/database或pear-admin-layui）在安装过程中，会尝试调用这些被禁用的函数，从而导致安装过程中断或静默失败。

• 正确的做法是：执行composer require -W illuminate/database。这里的-W参数，就是告诉Composer忽略平台限制，跳过对禁用函数的检查。
• 安装webman/admin这类插件时，同样需要加上此参数：composer require -W webman/admin。
• 安装完成后，务必去config/plugin/目录下检查是否生成了对应的插件配置目录，而不要只确认vendor/文件夹里有代码。

start.php 里的 require_once 链路不能动

这是Webman启动机制的核心，也是容易出问题的地方。Webman的启动并不完全依赖Composer的自动加载机制来兜底，而是依靠start.php文件顶部那一连串硬编码的require_once语句来加载核心类和配置。一旦你移动了vendor目录的位置、修改了BASE_PATH常量，或者不小心删掉了某一行require，立刻就会遭遇Class 'WebmanApp' not found这类致命错误。

• 首要原则：不要手动修改start.php中的路径加载逻辑。尤其要确保__DIR__ . '/vendor/autoload.php'这一行指向的位置绝对正确。
• 如果你对项目结构进行了调整（例如将Webman放入某个子目录），那么第一件事就是同步更新start.php里的BASE_PATH常量以及所有require_once的路径。
• 有个简单的验证方法：你可以尝试删除vendor/autoload.php文件，然后再次运行php start.php start。如果项目还能启动，那就说明它根本没走Composer的自动加载，完全是靠start.php里的手动引用来完成的。

插件配置合并机制依赖 config/plugin/ 目录结构

Webman插件的加载逻辑也独树一帜。它不通过Composer的autoload来加载插件业务逻辑，而是通过扫描config/plugin/{vendor}/{name}/这个特定目录结构下的配置文件（如app.php、route.php），并自动将它们合并到主配置中。这意味着：

• 插件必须将其配置文件安装到config/plugin/下对应的路径中，仅仅在vendor/目录里有代码是远远不够的。
• 例如，config/plugin/webman/admin/app.php这个文件会被框架自动读取并注入服务提供者。但如果你把它错误地放在了config/plugin/admin/目录下，配置就不会生效。
• 插件自身的composer.json里即使声明了autoload配置，也主要是在开发时用于IDE的代码提示，在Webman运行时并不生效。真正起作用的，是config/plugin/目录下的那些配置文件。

最后，也是最容易被忽略的一点：Webman的Composer使用逻辑是“配置驱动”的，而非单纯的“类加载驱动”。你或许改对了composer.json，成功安装了依赖，但如果start.php的加载链路和config/plugin/的目录结构没有正确跟上，那么所有的依赖安装都等于白费功夫。