PHP项目项目文档如何自动提取生成

wen PHP项目 2026-06-29 281

本文目录导读：

PHP项目项目文档如何自动提取生成

基于 PHPDoc 注解的文档生成（最常用）
基于代码分析的工具
框架专用工具
自动化与CI/CD集成
Markdown格式文档工具
最佳实践建议

为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系统