phpDocumentor 完全指南：從安裝到規範註釋的最佳實踐

什麼是 phpDocumentor？

phpDocumentor（舊稱 PHPDoc）是 PHP 專案的標準文件產生工具，從原始碼的 DocBlock 註釋自動產生 HTML/PDF/CHM 等格式的 API 文件。它強制開發者撰寫結構化註釋，提升程式碼可讀性與維護性。

安裝與執行

方式 1：Composer 全域安裝（推薦）

composer global require phpdocumentor/phpdocumentor
# 確保 ~/.composer/vendor/bin 在 PATH 中
phpdoc -d ./src -t ./docs/api

方式 2：專案本地安裝

composer require --dev phpdocumentor/phpdocumentor
./vendor/bin/phpdoc -d ./src -t ./docs/api

方式 3：Docker 執行（無污染環境）

docker run --rm -v $(pwd):/data phpdoc/phpdoc:latest \
  -d /data/src -t /data/docs/api

常用參數速查

DocBlock 註釋規範全攻略

基本結構

/**
 * 簡短描述（單行，結尾有句點）
 *
 * 詳細描述（可多行，支援 Markdown）
 * 
 * @tag 值
 * @tag 參數1 參數2 描述
 */

檔案層級註釋

<?php
/**
 * 使用者管理服務
 *
 * 處理使用者註冊、認證、授權等核心業務邏輯
 *
 * @package App\Services
 * @author  張三 <zhangsan@example.com>
 * @version 2.1.0
 * @license MIT
 */

類別註釋

/**
 * 使用者實體類別
 *
 * 代表系統中的使用者，包含基本資料與認證相關屬性
 *
 * @package App\Models
 * @property int    $id
 * @property string $email
 * @property string $name
 * @property Carbon $created_at
 * @method  static User find(int $id)
 * @method  static User where(string $column, mixed $value)
 */
class User extends Model {
    // ...
}

屬性註釋

class User {
    /**
     * 使用者唯一識別碼
     * @var int
     * @readonly
     */
    protected $id;

    /**
     * 電子郵件（唯一）
     * @var string
     * @validate email|unique:users
     */
    protected $email;

    /**
     * 角色關聯
     * @var Role|Collection
     */
    protected $roles;
}

方法/函數註釋（核心）

/**
 * 依條件查詢使用者
 *
 * @param array $filters 過濾條件 ['email' => '...', 'status' => 1]
 * @param int   $limit   最大筆數（預設 15）
 * @param string[] $columns 要選取的欄位（預設 ['*']）
 * @return User[]|Collection 使用者集合
 * @throws \InvalidArgumentException 當 $filters 為空陣列
 * @example
 *   $users = $service->findUsers(['status' => 1], 10);
 * @see UserRepository::query()
 * @deprecated 2.0 使用 UserRepository 取代
 * @todo 加入快取機制
 */
public function findUsers(array $filters = [], int $limit = 15, array $columns = ['*']) {
    if (empty($filters)) {
        throw new \InvalidArgumentException('Filters cannot be empty');
    }
    // ...
}

常用標籤完整對照表

型別表示法規範（PSR-5 / PHPStan 相容）

最佳實踐檢查清單

• [ ] 所有 public/protected 類別、方法、屬性皆有 DocBlock
• [ ] 型別宣告與實際程式碼一致（搭配 PHPStan 靜態分析驗證）
• [ ] @param/@return 描述「什麼情況回傳什麼」，而非重複型別
• [ ] 例外情況完整標註 @throws
• [ ] 棄用功能標註 @deprecated 並指引替代方案
• [ ] 複雜邏輯補充 @example 或詳細描述
• [ ] 執行 phpdoc --validate 檢查語法錯誤
• [ ] CI/CD 整合文件自動產生與發布

現代替代方案

優秀的文件不是事後補充，而是開發過程的副產品。養成「寫代碼前先寫 DocBlock」的習慣，配合靜態分析工具驗證，才能讓文件真正成為專案的資產而非負擔。

1. 上一篇文章： 徹底解決 phpMyAdmin 登入逾時問題：修改 LoginCookieValidity 完整指南
2. 下一篇文章： PHP 實作多搜尋引擎跳轉：關鍵字導向 Google、Yahoo、百度

PHP 相關知識

PHP 串接 Dropbox API 完整教學：OAuth 2.0 認證、檔案上傳下載與列表操作

前言 Dropbox 提供 RESTful API 讓應用程

用 PHP 建構靜態網站模板框架（四）：輸出緩衝實現「三行接入」完整架構

最終形態：每頁僅三行 PHP <?php requir

phpcms V9 點擊數機制深度解析：從模板標籤到數據模型

phpcms V9 點擊數機制深度解析：從模板標籤到數據模型

IIS 7.5 配置 PHP 環境圖文教程（Windows 7/8/Server 2008 R2）

IIS 7.5 搭建 PHP 運行環境完整步驟 IIS 7.