Composer如何配合PHPDoc生成文档_Composer配合PHPDoc生成文档解析-composer-PHP中文网

composer install 不会自动触发 phpdoc 生成，因其仅负责依赖管理与脚本执行；phpdoc 是独立工具，需通过 composer.json 的 scripts 显式配置（如 "docs" 命令）并手动运行，或结合 phpdoc.xml 配置调用。

composer如何配合phpdoc生成文档_composer配合phpdoc生成文档解析

为什么 `composer install` 不会自动触发 PHPDoc 生成

Composer 本身不处理文档生成，它只管依赖安装和脚本执行。PHPDoc（如 phpdocumentor）是独立工具，需要显式调用或通过 Composer 脚本绑定。常见误解是以为加了 require-dev 就能自动生成文档——其实只是把工具装进 vendor/bin/，后续步骤全靠手动或配置驱动。

真正起作用的是 composer.json 中的 scripts 段，它让 composer run docs 这类命令成为可能。

PHPDoc 工具（如 phpdocumentor/phpdocumentor）必须放在 require-dev 里，否则 vendor/bin/phpdoc 不会出现
不能依赖 post-install-cmd 自动跑文档生成——开发环境每次 composer install 都生成一次文档，既慢又没必要
phpdoc 命令默认不读取 composer.json，需额外配置 phpdoc.xml 或用 --directory 指定源码路径

如何用 Composer 脚本一键运行 phpdocumentor

在 composer.json 的 scripts 下添加自定义命令，是最轻量、最可复用的方式。这样团队成员只需执行一条命令，无需记参数或路径。

示例配置（支持 PHP 8.0+ 和 phpdocumentor v3）：

Workflow Decomposer

工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。

下载

"scripts": {
  "docs": [
    "php -d memory_limit=-1 vendor/bin/phpdoc --config=phpdoc.xml"
  ],
  "docs:watch": "php -d memory_limit=-1 vendor/bin/phpdoc --config=phpdoc.xml --force --quiet --template=clean"
}

memory_limit=-1 很关键：大型项目解析注释容易 OOM，尤其含大量 trait 或泛型模拟注释时
--config=phpdoc.xml 推荐使用配置文件而非长命令行，便于维护路径、忽略目录、模板选择等
--force 强制重生成（避免缓存导致文档未更新），--quiet 减少干扰输出
不要把 docs 放进 post-autoload-dump ——每次 composer dump-autoload 都跑一遍文档，纯属浪费时间

phpdoc.xml 配置里最容易错的三处

phpdoc.xml 是 phpdocumentor v3 的标准配置，但很多用户复制旧模板后卡在路径、版本或插件上。核心不是“写全”，而是确保三处匹配真实项目结构。

<paths><source>./src</source></paths>：必须指向实际 PHP 类所在目录，不是 ./ 或 ./app；若用 Laravel，通常应为 ./app 或 ./src，而非 ./vendor
<version number="*"></version>：设成 * 才会按 composer.json 的 version 字段自动填入文档页眉；设成固定字符串（如 "1.0"）会导致版本硬编码，后续发版要手动改
<transformations></transformations> 中若启用了 psalm 或 phpstan 插件，但项目没装对应分析器，phpdoc 会静默失败或报 Class not found 错误——先删掉插件段再逐步加回

生成的文档打不开？检查 output 目录权限和 URL 路径

phpdocumentor 默认输出到 ./output，但直接双击 index.html 会因浏览器同源策略报 JS 加载失败（Failed to load resource: net::ERR_FILE_NOT_FOUND）。这不是代码问题，是本地文件协议限制。

正确做法：用简易 HTTP 服务预览，例如 cd output && php -S localhost:8000
若部署到 Nginx/Apache，确保 output 目录被设为 web root 子目录（如 /var/www/html/docs），且 index.html 可被直接访问
生成后检查 output/.buildinfo 文件是否存在——没有它说明构建中途退出，大概率是某处 PHPDoc 注释语法错误（如 @param $foo string 缺少变量名）
CI 环境中记得加 --no-interaction 参数，否则 phpdoc 可能卡在交互式确认上