萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP 文檔生成神器:phpDocumentor 完整安裝與使用指南

為什麼需要 phpDocumentor?

  • 手寫 API 文檔:枯燥、易過時、不一致
  • phpDocumentor:從原始碼自動解析 生成文檔
  • 支援:類別繼承關係圖、方法簽名、參數/回傳型別、@param/@return/@throws 註解
  • 輸出格式:HTML (預設)、CHM、PDF、XML
  • 支援 PHP 5+ 語法 (舊版 phpDoc 僅支援 PHP 4)

安裝步驟 (PEAR)

# 1. 進入 PHP 安裝目錄
cd /usr/local/php  # 或你的 PHP 路徑

# 2. 安裝
pear install phpDocumentor

# 3. 驗證
phpdoc -h

安裝完成會產生 phpdoc.bat (Windows) / phpdoc (Linux/Mac) 執行檔。

基本使用

# 最簡單:掃描目錄生成 HTML 到預設 output/
phpdoc -d /path/to/source -t /path/to/output

# 完整參數
phpdoc \
  -d /var/www/project/src \
  -t /var/www/docs/api \
  -ti "My Project API" \
  -dn "MyProject" \
  -o HTML:Smarty:PHP \
  -ric "README.md" \
  -ue "*.phtml" \
  --ignore "vendor/,tests/" \
  --visibility "public,protected" \
  --template "responsive-twig"

常用參數表

參數說明
-d, --directory掃描來源目錄 (可多個,逗號分隔)
-t, --target輸出目錄
-ti, --title文檔標題
-dn, --defaultpackagename預設套件名稱
-o, --output輸出格式:HTML:Smarty:PHP, CHM:default:default, PDF:default:default
-ric, --readmeinstallchangelog包含 README/INSTALL/CHANGELOG
-ue, --undocumentedelements包含無註解元素
--ignore排除目錄/檔案模式
--visibility最低可見度:public/protected/private
--template模板主題 (responsive-twig 為現代預設)

DocBlock 註解標籤速查

/**
 * 類別簡短描述
 * 
 * 詳細說明可跨多行,支援 Markdown。
 * 
 * @package    MyProject\Core
 * @subpackage Database
 * @author     John Doe <john@example.com>
 * @version    1.2.3
 * @since      2023-01-15
 * @deprecated 使用 NewClass 替代
 */
class Database {
    /**
     * @var PDO 資料庫連線
     */
    private $pdo;
    
    /**
     * 建構子
     * 
     * @param array $config 連線設定 [host, dbname, user, pass, charset]
     * @throws InvalidArgumentException 設定缺失
     */
    public function __construct(array $config) { ... }
    
    /**
     * 執行查詢
     * 
     * @param string $sql    SQL 語句
     * @param array  $params 繫結參數
     * @return array|false   結果集或 false
     * @throws PDOException  查詢失敗
     */
    public function query($sql, array $params = []) { ... }
}

常用標籤表

標籤用途範例
@var屬性型別@var PDO
@param方法參數@param int $id 使用者 ID
@return回傳值@return User|null
@throws拋出例外@throws Exception
@see參考連結@see OtherClass::method()
@link外部連結@link https://example.com
@deprecated棄用說明@deprecated since 2.0 use newMethod()
@todo待辦事項@todo 加入快取
@property魔術屬性@property string $name
@method魔術方法@method User findById(int $id)

現代替代方案

  • Sami:Symfony 專案常用、速度快、Twig 模板
  • phpDox:XML 為基礎、支援圖表、持續整合友善
  • Doctum:phpDocumentor 分支、專注 PHP 5.3+
  • IDE 內建:PhpStorm、VS Code (PHP Intelephense) 即時顯示 DocBlock

CI/CD 整合

# .gitlab-ci.yml
doc:
  stage: deploy
  image: php:8.2-cli
  script:
    - composer install --no-dev
    - vendor/bin/phpdoc -d src -t public/docs/api
  artifacts:
    paths: [public/docs/api]
    expire_in: 30 days
copyright © 萬盛學電腦網 all rights reserved