您现在的位置：程式碼之家 >> 編程語言 > >> 網頁程式設計 >> PHP 程式設計 >> PHP 相關知識

phpDocumentor 3 安裝與使用完整指南 (現代版)

編輯：PHP 相關知識

phpDocumentor 簡介

phpDocumentor 是 PHP 專案文件產生器標準工具，從原始碼的 DocBlock 註解自動生成完整 API 文件。現代版本 (v3.x) 支援 PHP 7.4+、屬性語法、Markdown 格式、Twig 模板客製化。

安裝方式比較

方式	適用場景	指令
Composer 專案安裝	推薦，納入專案依賴	`composer require --dev phpdocumentor/phpdocumentor`
全域安裝	多專案共用、CI 環境	`composer global require phpdocumentor/phpdocumentor`
PHAR 檔案	無 Composer 環境、快速試用	下載 `phpDocumentor.phar` 直接執行
Docker	容器化環境、版本隔離	`docker run --rm -v $(pwd):/data phpdoc/phpdoc:3 run -d /data/src -t /data/docs`

基本使用流程

# 1. 專案安裝後，使用 vendor/bin 執行
vendor/bin/phpdoc -d src -t docs/api

# 參數說明：
# -d, --directory     要掃描的原始碼目錄 (可多次指定)
# -t, --target        輸出目錄
# -f, --filename      指定單一檔案
# --encoding          原始碼編碼 (預設 UTF-8)
# --template          使用模板 (預設 clean, 可選 responsive, abstract 等)
# --config            使用設定檔 (phpdoc.xml.dist)

設定檔最佳實踐 (phpdoc.xml)

<?xml version="1.0" encoding="UTF-8"?>
<phpdoc>
    <title>My Project API Documentation</title>
    <parser>
        <target>docs/api</target>
        <extensions>
            <extension>php</extension>
        </extensions>
        <encoding>UTF-8</encoding>
        <ignore-tags>
            <tag>internal</tag>
        </ignore-tags>
        <visibility>public,protected</visibility>
    </parser>
    <transformer>
        <template>responsive</template>
    </transformer>
    <files>
        <directory>src</directory>
        <file>README.md</file>
    </files>
</phpdoc>

DocBlock 註解標準寫法

<?php
/**
 * 使用者服務類別
 * 
 * 處理使用者註冊、登入、資料管理等核心業務邏輯
 * 
 * @package App\Services
 * @author 開發團隊 <dev@example.com>
 * @version 2.1.0
 * @since 1.0.0
 */
class UserService 
{
    /**
     * 註冊新使用者
     * 
     * @param string $email      使用者信箱 (唯一)
     * @param string $password   明文密碼，將自動雜湊
     * @param array  $profile    選填個人資料 ['name', 'avatar', 'bio']
     * @return User              建立的使用者實體
     * @throws ValidationException  資料驗證失敗
     * @throws BusinessLogicException 信箱已存在
     * @example
     * $user = $service->register('test@example.com', 'password123', ['name' => '張三']);
     */
    public function register(string $email, string $password, array $profile = []): User
    {
        // 實作...
    }
}

常用標籤速查表

標籤	用途	範例
`@param`	方法參數	`@param string $name 使用者名稱`
`@return`	回傳值	`@return User\|null 使用者物件或 null`
`@throws`	拋出異常	`@throws NotFoundException 找不到資源`
`@var`	屬性/變數型別	`@var PDO $connection 資料庫連線`
`@see`	參考連結	`@see UserRepository::find()`
`@deprecated`	標記棄用	`@deprecated since 2.0 use newMethod()`
`@internal`	內部使用，不出現在公開文件	`@internal`

PHP 8+ 屬性語法支援

<?php
use Attribute;
use PhpDoc\Annotation\Param;
use PhpDoc\Annotation\Return_;

#[Attribute]
class ApiEndpoint {
    public function __construct(
        public string $method,
        public string $path,
        public string $description
    ) {}
}

class UserController 
{
    #[ApiEndpoint('GET', '/users/{id}', '取得使用者資料')]
    #[Param('id', 'int', '使用者 ID')]
    #[Return_('User', '使用者物件')]
    public function show(int $id): User { /* ... */ }
}

CI/CD 整合範例 (GitHub Actions)

# .github/workflows/docs.yml
name: Generate API Docs
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
      - run: composer install --no-interaction
      - run: vendor/bin/phpdoc -c phpdoc.xml
      - uses: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/main'
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/api