為什麼需要 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