PHP 文档生成器的对决：PhpDocumentor2 Vs Sami

您是否也在找一款心仪的 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.