本文目录导读：
为PHP项目自动生成文档,通常有几种主流方案，以下按工具类型和生成方式进行分类说明：
基于 PHPDoc 注解的文档生成（最常用）
phpDocumentor
这是PHP最经典的文档生成工具,通过解析代码中的PHPDoc注释生成API文档。
安装方式：
# 全局安装（推荐） composer global require phpdocumentor/phpdocumentor # 或仅在项目中安装 composer require --dev phpdocumentor/phpdocumentor
使用方式：
# 生成HTML文档（会扫描当前目录所有PHP文件） php vendor/bin/phpdoc # 指定源目录和输出目录 php vendor/bin/phpdoc -d ./src -t ./docs
示例代码注释：
<?php
/**
* 用户管理类
*
* 处理用户注册、登录、信息管理等功能
*
* @package App\Service
* @author 作者名
* @version 1.0.0
*/
class UserService
{
/**
* 用户注册
*
* @param string $username 用户名
* @param string $password 密码（已加密）
* @return array{id: int, token: string} 返回用户ID和Token
* @throws \InvalidArgumentException 当用户名已存在时
*/
public function register(string $username, string $password): array
{
// 业务逻辑...
}
}
生成效果：
- 类、方法、属性的完整文档
- 支持自定义模板
- 可以生成HTML、PDF、CHM等格式
Sami（现已更名为 "phpDocumentor 3"）
比传统phpDocumentor更现代的替代品,支持Symfony、Laravel等框架。
配置示例：
<?php
// sami.php
use Sami\Sami;
use Symfony\Component\Finder\Finder;
$iterator = Finder::create()
->files()
->name('*.php')
->in(__DIR__ . '/src')
;
return new Sami($iterator, [ => 'My PHP Project API',
'build_dir' => __DIR__ . '/docs/build',
'cache_dir' => __DIR__ . '/docs/cache',
'default_opened_level' => 2,
]);
运行：
php vendor/bin/sami.php update sami.php
基于代码分析的工具
Doxygen
虽然主要面向C++，但通过配置也可以很好支持PHP（需要将PHP文件当作C风格解析）。
配置示例（Doxyfile）：
INPUT = ./src
FILE_PATTERNS = *.php
RECURSIVE = YES
EXTRACT_ALL = YES
OPTIMIZE_OUTPUT_FOR_C = NO 特点：
- 支持调用图、继承图等图表生成
- 支持多种输出格式（HTML、PDF、LaTeX）
- 对PHP支持不如专用工具完善
框架专用工具
Laravel专属：Laravel IDE Helper
虽然主要用于IDE辅助,但配合阅读工具也可作为文档使用。
composer require --dev barryvdh/laravel-ide-helper # 生成Facade、Model等文档 php artisan ide-helper:generate php artisan ide-helper:models
Symfony专属：ApiDoc Bundle
用于生成REST API文档：
composer require --dev nelmio/api-doc-bundle
配置路由注解后访问 /api/doc 即可看到Swagger风格的文档。
自动化与CI/CD集成
GitHub Actions + phpDocumentor
# .github/workflows/docs.yml
name: Generate Documentation
on:
push:
branches: [ main ]
jobs:
docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: '8.1'
- name: Install dependencies
run: composer install --no-interaction
- name: Generate docs
run: vendor/bin/phpdoc -d src -t docs
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./docs
GitLab CI
# .gitlab-ci.yml
stages:
- docs
generate-docs:
stage: docs
script:
- composer install
- vendor/bin/phpdoc -d src -t public/docs
artifacts:
paths:
- public/docs
only:
- main
Markdown格式文档工具
phpDocumentor Markdown 模板
为phpDocumentor配置Markdown输出：
composer require --dev phpdocumentor/template-markdown php vendor/bin/phpdoc --template="markdown"
API Platform + OpenAPI
如果你的项目是REST API，可以集成OpenAPI/Swagger：
composer require api-platform/api-pack
自动生成符合OpenAPI规范的API文档（JSON/YAML格式），再通过Swagger UI展示。
最佳实践建议
| 场景 | 推荐工具 | 说明 |
|---|---|---|
| 传统PHP项目 | phpDocumentor | 最成熟，社区支持好 |
| Laravel项目 | Laravel IDE Helper + phpDocumentor | IDE辅助+完整文档 |
| REST API项目 | NelmioApiDocBundle / API Platform | 自动生成接口文档 |
| 需要CI集成 | phpDocumentor + GitHub Actions | 自动部署到GitHub Pages |
| 需要Markdown输出 | phpDocumentor Markdown模板 | 用于导入到Wiki系统 |
实施步骤：
- 团队统一PHPDoc注释规范（推荐PSR-5/PSR-19标准）
- 在项目中配置文档生成工具
- 集成到CI/CD流水线，每次合并自动生成
- 将生成的文档部署到内部服务器或GitHub Pages
注意事项：
- PHPDoc注释质量直接影响文档质量
- 建议在Pre-commit钩子中检查注释完整性
- 对于大型项目,文档生成可能耗时较长，建议增量生成
