composer本身不生成文档，所有“自动生成”均依赖外部工具（如phpdocumentor）和显式配置scripts；需在composer.json中定义语义化命令（如"docs"），确保require-dev已安装工具、路径正确且环境兼容。
composer 本身不生成文档，所有“自动生成”都依赖外部工具 + 显式配置。直接运行 composer install 或 composer dump-autoload 不会产出任何 HTML、Markdown 或 API 手册。
composer.json 的 scripts 是文档生成的唯一入口
你得手动定义命令，让 Composer 成为调度器，而不是生成器。
- 脚本名建议用语义化名称，比如
docs、docs:api、docs:deps，避免和内置命令（如test、lint）冲突 - 值可以是字符串或字符串数组；多步骤推荐用数组，保证顺序执行
- 必须确保工具已装在
require-dev里，且vendor/bin/下存在对应二进制（如phpdoc、doctum） - Windows 用户注意：
vendor/bin/phpdoc可能是phpdoc.bat，脚本中写全路径更稳
示例（安全写法）：
"scripts": {
"docs": [
"rm -rf docs/api",
"php -d memory_limit=-1 vendor/bin/phpdoc --config=phpdoc.xml"
],
"docs:deps": "composer show -f json | jq '[.packages[] | select(.type == \"library\") | {name: .name, version: .version, homepage: .homepage}]' > docs/dependencies.json"
}
phpdoc.xml 配置里三处不匹配就白跑
phpdocumentor v3 读取 phpdoc.xml，但很多人复制模板后卡在路径或版本上。
Discussion Composer
下载
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
-
<directory></directory>标签不存在，正确写法是<fileset></fileset>包裹<directory></directory>，且路径必须相对于phpdoc.xml所在位置，不是项目根目录 -
<output></output>建议固定为docs/api，方便 CI 部署到 GitHub Pages 或内部 Nginx -
<version number="<em>"></version>中的才会从composer.json的version字段自动取值；写死成"1.0"就不会更新
漏掉 <exclude></exclude> 会导致扫描 Tests 或 Fixtures 目录，拖慢速度还污染文档索引。
composer show -f json 导出依赖清单时的兼容性陷阱
这个命令是企业级文档库的数据底座，但低版本 Composer 会直接报错。
-
--format=json在 Composer 2.2 以下不支持，错误信息是Unrecognized option: --format - 必须加
--all才包含require-dev中的工具链（如phpstan/phpstan），否则只导出运行时依赖 - 私有包若使用自定义
repositories，composer show输出里source字段会显示 URL，但不会标记是否来自内网源——审计时容易误判
建议在 CI 中加校验：
composer --version | grep -q "2\.[2-9]" || (echo "Composer too old"; exit 1)
真正难的不是写几行脚本，而是决定哪些内容该进文档、哪些不该进，以及谁来维护更新节奏。比如 post-update-cmd 触发文档生成看似省事，但开发者拉取新依赖时若本地没装 jq 或 phpdoc，就会静默失败——而错误日志往往被 --quiet 吞掉。
