phpDocumentor 分析您的代码创建优秀的 API 文档

Question

PHPDocumentor 是一个用 PHP 写的强大的文档自动生成工具，对于有规范注释的 PHP 程序，能够快速生成具有结构清晰、相互参照、索引等功能的 API 文档，文档可以转换为PDF、HTML、 CHM 等格式的文档，这样非常有利于代码的升级、维护、移交等操作。

为什么要使用 phpDocumentor？

PHPDocumentor 可以直接从代码的注释中找到有用的信息，并生成索引帮助文档，这样你就不必要再去翻找那些复杂的代码文件，PHPDocumentor 并不是要取代 API 文档，而是提供一种帮助文档或者是附加文档，从下面的几个方面被证明很有帮助：

• 提供一个API库或者索引文档，使用在线搜索
• 作为一个插件运行在项目中，例如 WordPress 或者是 PyroCMS
• 长期运行的复杂项目，快速查找可供使用的函数或方法

文档模板

PHPDocumentor 拥有多种风格的文档模板，你可以完全自定义文档的输出方式，通过修改 CSS 文档来调整文档的显示效果，应用到符合你的品牌推广风格的文档样式。

代码分析

phpDocumentor 2 能够提取有趣的信息，并以图形和报告的形式呈现出来。当前的版本支持以下内容：

• 显示所有子类化和接口实现的继承关系图。
• 报告源代码内联文档中的错误。
• 报告哪些元素标记为已弃用。
• 报告 todo 在代码中的位置以及要执行的操作。

这个列表只会在将来持续增长，以帮助您确定在哪里投资资源改进代码，从而使您的代码更加稳定和可维护性。

结构和功能

PHPDocumentor 是全部采用 OOP 的思想来编写的，这也是 PEAR 所推荐的方式，PHPDocumentor 的工作原理：

PHPDocumentor 扫描指定目录下面的 PHP 源代码，扫描其中的关键字，截取需要分析的注释，然后分析注释中的专用的 tag，生成 xml 文件，接着根据已经分析完的类和模块的信息，建立相应的索引，生成 xml 文件对于生成 的 xml 文件，使用定制的模板输出为 html 文件。

从设计上来说，PHPDocumentor 使用了2个超类：PhpdocObject 和 PhpdocError。这是 整个 PHPDocumentor 的基本类，这种方式也是 PEAR 所推荐的。当你编写应用框架时，最好能够有一个基本的超类，而其他的子类或者是功能类都有一个共同的祖先。

在扫描源代码过程中，PHPDocumentor 使用的是类似 GREP 的形式。PHPDocumentor 令人满意的另一方面是其分析结果是以 XML 形式保存的，这就意味着其他应 用程序可以共享这个数据，同时 PHPDocumentor 也提供了相应的接口，你可以实现这个接口，把 API 文档生成其他的形式，比如 PDF、LATEX、WORD 等。 目前 PHPDocumentor 的分析结果可以以 HTML 形式表现，由于使用了模板机制，可以很方便地定制风格。

使用 pear 安装使用

安装方式有两种，一是下载源码安装，另一种是通过 pear 安装。

安装 pear

使用 dos 窗口进入 php 安装目录，有个文件叫 go-pear.bat，如果没有，建议到网上下载 go-pear.phar，然后在 dos 窗口下运行 go-pear.phar，从而安装 pear。

php go-pear.phar

安装 phpdoc

Pear install phpDocumentor

在 phpDocumentor 成功安装后，php 安装目录下会多出来一个 phpdoc.bat。这个文件就是我们用来生成文档的批处理文件。

在 phpdoc.bat 所在目录下，输入

Phpdoc –h

会得到一个 phpDocumentor 的详细参数列表。先看看最重要的几个吧：

• -d 这个目录代表着需要生成文档的原始 php 文件目录（注意是目录）
• -t 这个目录代表着生成的文档存放目录
• -o 这个参数代表着生成的文档格式，例如 html 格式，参数就是 HTML:frames:phpedit

生成文档

生成文档的命令就是：

phpdoc -d "D:\phpdoc\1" -t "D:\phpdoc\1" -o "HTML:frames:phpedit"

可以看到，解析完成后，在目标目录下生成很多 html 文件，打开 index.html 文件，就是我们需要的文档。

使用源码安装使用

下载 PHPDoc 压缩文件（phpdoc.zip），地址如下：

https://github.com/phpDocumentor/phpDocumentor2/releases

解压到某一个目录，打开 phpdoc.bat 编辑第16行：

SET phpCli=D:\xampp\php\php.exe

配置 phpCli 为自己 php.exe 文件的路径即可。

打开 DOS 窗口，进入文件的解压目录，然后执行解析文档命令即可。

phpdoc -d "D:\phpdoc\1" -t "D:\phpdoc\1" -o "HTML:frames:phpedit"

phpDocumentor2 安装使用

安装 pear（同上）

此处给出下载地址：http://pear.php.net/go-pear.phar

将 go-pear.phar 放到 PHP 目录下执行安装命令：

php go-pear.phar

下面会执行输入 system，然后一路回车安装完毕。

接下来安装类关系绘图用到的工具

pear install image_graphviz

下载 http://www.graphviz.org/Download_windows.php graphviz-2.38.msi

安装后，注意环境变量 path 添加上该 bin 的路径，重启电脑，否则无法生效

安装 phpDocumentor

pear channel-discover pear.phpdoc.org 
pear install phpdoc/phpDocumentor

稍等一会，安装步骤完成！

注意：两个软件安装后的目录都在 PHP 下的 pear 下面：

php/pear/PhpDocumentor
php/pear/Image

中文乱码问题

在实际的使用中我发现生成的文档不支持中文，后 Google 搜索得知，PhpDocumentor 的默认编码是 iso-8859-1 的，项目文件都是 utf8 编码的，所以需要把编码改成utf-8才可以，进入 PhpDocumentor 的模板目录把模板文件修改成 utf-8 编码：

pear-data/PhpDocumentor/phpDocumentor/Converters

下面的文件都转换为 utf-8 编码的文件，再生成项目文档，浏览项目中中文乱码解决。

相关链接

• 官网：https://phpdoc.org/
• Github 地址：https://github.com/phpDocumentor/phpDocumentor2
• 帮助文档：https://www.wenjiangs.com/docs/phpdoc