您是否也在找一款心仪的 PHP API 文档生成工具?如果是你来对地方了,因为接下来我将请出经典巨星 PhpDocumentor 和新星 Sami 一起上台来做一个对比。
这里单独提一下 Sami,估计很多人都没听说过。这个项目开始于 2012,作者为 Symfony2 项目的主导人 Fabien Potencier,目前 Symfony2 的 API 文档就是由它来生成的。Fabien 也写了一篇介绍性的文章(英文),大家可以看看。
另外本文里的 PhpDocumentor 都指 PhpDocumentor2,功能是在没有扩展的情况下。
功能
PhpDocumentor | Sami | |
---|---|---|
可更换主题 | yes(模板支持twig) | yes(模板支持twig) |
可扩展 | yes | yes* |
错误日志 | yes | |
支持多种格式 | HTML,PDF | |
响应式布局 | yes | |
继承/依赖图谱 | yes | |
支持Markdown | yes | |
搜索 | yes | |
版本管理 | yes(支持git) |
注:Sami 的配置文件是 PHP 文件,非常灵活,甚至可以获取到依赖注入服务对象,这样你就可以任意修改他所使用的组件
功能上各有千秋,PhpDocumentor 看上去略胜一筹,不过如何选择还是看个人喜好,比如说我更倾向使用 Sami,就因为可搜索,毕竟自己找还是不如搜索方便啊。
性能
我拿 Symfony2 项目做的测试,文件够多,生成的时间长,会更容易看出差异。
测试机器 Intel® Core™2 Duo CPU T6570 @ 2.10GHz × 2 | 4G DDR2 | Intel SSD
结果(使用 time
命令测试):
时间 | |
---|---|
Sami | 290.09s |
而 PhpDocumentor 在执行了55分钟我已经失去耐性的时候被我强行中断了……
然后我用 Symfony 其中一个组件 form 做了测试:
时间 | |
---|---|
PhpDocumentaion | 249.64s |
Sami | 43.79s |
可以看到 Sami 速度明显优于 PhpDocumentor,这可能跟 PhpDocument会生成错误报告和依赖/继承图谱,处理 markdown 等任务有关,不过慢得太多也就成了致命伤,而且图谱也是空的……
值得一提的是,Sami 支持增量生成文档。PhpDocumentor 似乎也有某种缓存机制,第二次运行时直接跳过了 parse 阶段,不过结果依然差强人意:
时间 | |
---|---|
PhpDocumentaion | 203.58s |
Sami | 6.94s |
这一轮 Sami 以绝对优势胜利
文档
好的项目的一个必备要素就是优秀的文档,可惜 PhpDocumentor 并不具备,有些部分还是空的;但相对于 Sami 来说还是好多了,因为 Sami 就根本没有文档……难道是因为 Fabien 认为 Sami 已经够简单以至于在项目的 README 里面提几句就行了吗……
这个环节上,优胜者是 PhpDocumentor
总结
通过以上的对比,也不能说孰优孰劣,只能说大家按需所取,我个人是倾向于 Sami,除了搜索功能以外,因为 Sami 的配置就是 PHP 文件,所以可以做许多灵活的设置。比如 Sami 指定路径的方式,除了字符串形式的路径外,可以是 Symfony\Finder 返回的迭代器对象,站在强大的的 Symfony\Finder 的肩膀上,你可以非常灵活的设置源文件读取路径。而且还支持通过 git version 生成不同版本的对应的文档,实用性相当高(代码来源):
<?php
use Sami\Sami;
use Sami\Version\GitVersionCollection;
use Symfony\Component\Finder\Finder;
$iterator = Finder::create()
->files()
->name('*.php')
->exclude('Resources')
->exclude('Tests')
->in($dir = '/path/to/symfony/src')
;
// generate documentation for all v2.0.* tags, the 2.0 branch, and the master one
$versions = GitVersionCollection::create($dir)
->addFromTags('v2.0.*')
->add('2.0', '2.0 branch')
->add('master', 'master branch')
;
return new Sami($iterator, array(
'theme' => 'symfony',
'versions' => $versions,
'title' => 'Symfony2 API',
'build_dir' => __DIR__.'/../build/sf2/%version%',
'cache_dir' => __DIR__.'/../cache/sf2/%version%',
'default_opened_level' => 2,
));
另外除了这两款 PHP 制作的文档生成工具以外,还有其他许多工具也是很优秀的,比如 Doxygen,
支持多种语言生成文档,而且支持更多的输出格式,也是值得关注的。
PHP 文档生成器的对决:PhpDocumentor2 Vs Sami by Chris Yue is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License.

写作累,服务器还越来越贵
求分担,祝愿好人一生平安
天使打赏人