phpDocumentor运行指南：从基础到高级配置

phpDocumentor运行指南：从基础到高级配置

phpDocumentor Documentation Generator for PHP 项目地址: https://gitcode.com/gh_mirrors/ph/phpDocumentor

快速入门

phpDocumentor是一个强大的PHP文档生成工具，能够自动从源代码注释中提取文档信息并生成专业的技术文档。让我们从最基本的运行方式开始。

基本运行命令

phpDocumentor运行只需要三个核心参数：

• -d 指定要扫描的项目目录（可指定多个）
• -f 指定要扫描的单个文件（可指定多个）
• -t 指定文档输出目录（可选）

典型的使用示例如下：

phpdoc -d src/ -f config/bootstrap.php -t docs/api/

重要说明：

1. 必须至少指定一个目录或文件进行扫描
2. 如果不指定输出目录，默认会在当前目录下生成.phpdoc/build/目录存放文档
3. 输出目录不会被自动清空，重复运行需要手动清理旧文件

配置文件使用

对于复杂的项目，推荐使用配置文件而非命令行参数。phpDocumentor支持两种配置文件：

1. phpdoc.dist.xml - 项目级配置文件，应提交到版本控制
2. phpdoc.xml - 用户级配置文件，应加入.gitignore

最佳实践：

• 将基础配置放在phpdoc.dist.xml中
• 个人定制配置放在phpdoc.xml中
• 可以使用--config参数指定自定义配置文件路径

文件扫描控制

phpDocumentor提供了多种方式来精确控制要扫描的文件范围：

包含文件/目录

• 使用-d包含整个目录及其子目录
• 使用-f包含特定文件
• 两种参数都可以多次使用

排除文件/目录

使用--ignore参数可以排除不需要扫描的内容：

# 排除vendor目录
phpdoc -d src/ --ignore "vendor/"

# 排除特定文件
phpdoc -d src/ --ignore "tests/ExampleTest.php"

# 使用通配符排除
phpdoc -d src/ --ignore "**/*Test.php"

注意：

• 使用通配符时要用双引号包裹
• 相对路径是相对于项目根目录而非当前目录

特殊文件处理

• 默认忽略隐藏文件，可通过--hidden=off包含
• 默认不跟踪符号链接，可通过--no-ignore-symlinks启用

文档外观定制

phpDocumentor提供了多种方式来定制生成的文档外观：

模板选择

使用--template参数选择模板，可以同时生成多种格式：

# 生成HTML和Checkstyle格式
phpdoc --template="clean" --template="checkstyle" -d .

# 等价写法
phpdoc --template="clean,checkstyle" -d .

基础定制

• --defaultpackagename - 设置默认包名
• --title - 设置文档标题

文件编码

默认使用UTF-8编码，可通过--encoding指定其他编码：

phpdoc -d src/ --encoding="ISO-8859-1"

文档内容控制

可见性控制

使用--visibility参数控制哪些元素会被包含在文档中：

# 只包含public和protected元素（默认）
phpdoc -d src/ --visibility="public,protected"

# 包含所有元素（包括private）
phpdoc -d src/ --visibility="public,protected,private"

# 只包含标记为API的元素
phpdoc -d src/ --visibility="api"

# 包含内部元素（@internal标记的）
phpdoc -d src/ --visibility="internal"

标签过滤

使用--ignore-tags排除特定标签：

# 不显示@deprecated和@ignore标签
phpdoc -d src/ --ignore-tags="deprecated,ignore"

标记(Markers)收集

phpDocumentor可以收集代码中的特殊标记（如TODO），默认收集TODO和FIXME：

// TODO: 需要优化这段代码
// FIXME: 这里有个潜在bug

可以通过--markers参数自定义要收集的标记：

# 收集TODO、FIXME和NOTE标记
phpdoc -d src/ --markers="TODO,FIXME,NOTE"

提示：TODO标记会被特殊处理，生成专门的报告页面。

通过以上配置选项，你可以完全控制phpDocumentor的文档生成过程，从简单的API文档到复杂的定制化文档都能轻松实现。

phpDocumentor Documentation Generator for PHP 项目地址: https://gitcode.com/gh_mirrors/ph/phpDocumentor