如何利用phpdoc生成项目文档？phpdoc@3如何下载使用

我们相信：世界是美好的，你是我也是。平行空间的世界里面，不同版本的生活也在继续...

本文讨论一下利用phpdoc生成php文档的方式方法。对，在python/go等新兴语言大行其道的今天，php作为世界上最好的语言，也是必须可以提一下的。本文中，苏南大叔想说一下phpdoc的基本安装及使用方法。编写为一个php项目后，如果项目中的函数注释等都是按照phpdoc的标准编写的话，实际上可以利用phpdoc一键生成项目文档信息。

苏南大叔的“程序如此灵动”博客，记录苏南大叔的代码编程经验文章。本文测试环境：win10，php@8.2.10，phpdoc@3.4.1，graphviz。

安装phpdoc

phpdoc的全称是phpDocument，官方网站是：

• https://www.phpdoc.org/

官方文档是：

• https://docs.phpdoc.org/3.0/

按照网上流传的教程，phpdoc有三种安装方式，分别是pear/composer/phar这几种方式。官方推荐的使用方式是：直接下载phpDocumentor.phar文件，然后赋予执行权限(chmod +x phpDocumentor.phar)后，利用php-cli执行。

phpDocumentor.phar的下载地址是：

• https://phpdoc.org/phpDocumentor.phar

phpdoc的顺利使用，【需要】安装graphviz这款软件，安装方式：

• https://newsn.net/say/graphviz.html

要求php版本

截至到发稿，最新版的phpdoc@3.4.1需要php@8及以上版本，所以，测试环境不得不做了些改变，安装了php@8.2.10-nts版本。当然，请根据你的测试环境的系统，自行安装对应的符合要求的php版本。

• https://windows.php.net/download/
• https://windows.php.net/downloads/releases/php-8.2.10-nts-Win32-vs16-x64.zip

否则会报错：

PHP Fatal error:  Composer detected issues in your platform: Your Composer dependencies require a PHP version ">= 8.1.0". You are running 7.4.29. in phar://E:/tools/others/phpDocumentor.phar/vendor/composer/platform_check.php on line 24

Fatal error: Composer detected issues in your platform: Your Composer dependencies require a PHP version ">= 8.1.0". You are running 7.4.29. in phar://E:/tools/others/phpDocumentor.phar/vendor/composer/platform_check.php on line 24

基础使用方式

php phpDocumentor.phar -d project/ -t docs/

参数设置：

• -d指定项目路径，苏南大叔的测试环境中，【必须写完整路径】，否则无法解析文件。【大bug：路径不存在也不会报错！！！】
• -t指定文档输出。
• --title=文档标题。

使用结果

试图使用phpdoc@3.4.1解析wordpress@6.3.1和laravel@10.6.2都无耻的失败了，各种警告各种错误提示。可见这个phpdoc的顺利使用，还是需要很多条件组合的。

运行phpdoc的环境，可能需要能正确运行对应项目的php，否则可能就无法解析了（可见其phpdoc原理并不是简单的正则表达式匹配）。

对于wordpress@6.3.1的文档解析，

• 需要在php.ini里面正确开启extension=mbstring和extension_dir=ext。
• 需要正确处理-d参数的完整路径。

最终执行的命令是：

php phpDocumentor.phar -d C:\Users\sunan\Desktop\test\php\wordpress-6.3.1-zh_CN\ -t wordpress --title="wordpress文档"

执行结果，如下图所示：

结束语

苏南大叔并么有自定义模版的需求，默认的clean模版就挺好的。所以，本文就是以说明phpdoc的安装和使用问题为主。更高级的模版定制，项目代码中的注释编写问题，就留待后续文章更新了。

• https://newsn.net/tag/php/

如果本文对您有帮助，或者节约了您的时间，欢迎打赏瓶饮料，建立下友谊关系。
本博客不欢迎：各种镜像采集行为。请尊重原创文章内容，转载请保留作者链接。