phpDocumentor 是 PHP 專案**標準化 API 文檔生成工具**,從原始碼的 DocBlock 註釋提取結構化資訊,生成 HTML/PDF/CHM 等格式文檔。現代版本 (v3+) 支援 PHP 8.1+、屬性、聯集型別、泛型等新特性。
# Composer 安裝 (專案級)
composer require --dev phpdocumentor/phpdocumentor
# 或全域安裝
composer global require phpdocumentor/phpdocumentor
# 生成文檔
vendor/bin/phpdoc -d src -t docs/api --template=clean
# 或使用配置檔 phpdoc.xml
vendor/bin/phpdoc -c phpdoc.xml
<?php
/**
* 這是摘要描述 (Summary) - 單行,以點號結束,會顯示在列表中。
*
* 這是詳細描述 - 可跨多行,支援 Markdown 語法,
* 詳細說明功能、演算法、副作用、使用範例等。
*
* @param string $name 用戶名稱
* @param int $age 年齡,必須大於 0
* @return bool 成功返回 true
* @throws InvalidArgumentException 年齡小於等於 0 時拋出
* @see UserRepository::findByName() 相關查詢方法
* @since 2.1.0
* @deprecated 3.0 將移除,請改用 UserService::register()
*/
function createUser(string $name, int $age): bool {
// ...
}
?>
| 標籤 | 用途 | 適用對象 | 範例 |
|---|---|---|---|
| @param | 參數說明 | function, method | @param int $id 用戶 ID |
| @return | 回傳值說明 | function, method | @return User|null 找不到回傳 null |
| @var | 屬性/變數型別 | property, variable | @var string[] $tags 標籤列表 |
| @property | 魔術屬性 | class | @property string $fullName 完整姓名 |
| @method | 魔術方法 | class | @method User find(int $id) |
| @throws | 拋出異常 | function, method | @throws NotFoundException 找不到 |
| @see | 參考連結 | 所有 | @see https://example.com/docs |
| @since | 起始版本 | 所有 | @since 1.5.0 |
| @deprecated | 棄用說明 | 所有 | @deprecated 2.0 Use newMethod() |
| @author | 作者資訊 | file, class | @author Name <email@example.com> |
| @copyright | 版權聲明 | file, class | @copyright 2024 Company Inc. |
| @license | 授權條款 | file, class | @license MIT |
| @package | 邏輯分組 | file, class | @package App\Services |
| @subpackage | 子分組 | class | @subpackage Authentication |
| @uses | 使用關係 | function, method | @uses Cache::get() 使用快取 |
| @internal | 內部說明(不輸出文檔) | 所有 | @internal 暫時硬編碼,待重構 |
| @inheritdoc | 繼承父類文檔 | method, property | @inheritdoc |
| @mixin | Trait 混入 | class | @mixin TimestampableTrait |
| @template | 泛型參數 | class, method | @template T of EntityInterface |
| @psalm-*/@phpstan-* | 靜態分析輔助 | 所有 | @psalm-suppress MixedAssignment |
<?php
// 基礎型別
@param int $id
@param string $name
@param bool $active
@param float $price
@param array $tags
@param callable $callback
@param resource $handle
@param object $entity
@param iterable $items
@param mixed $data
// 類/介面型別
@param User $user
@param \App\DTO\UserDTO $dto
@param DateTimeInterface $createdAt
// 陣列詳細型別
@param string[] $names // 索引陣列
@param array $names // PHP 8.1+ / Psalm/PHPStan 語法
@param array $usersByEmail // 關聯陣列
// 可為 null
@param string|null $nickname
@param ?string $nickname // PHP 8.0+ 簡寫
// 聯集型別
@param string|int $id
@param User|Admin|Guest $actor
// 可呼叫型別
@param callable(string): bool $filter
@param Closure(User): User $transformer
// 物件形狀 (PHPStan/Psalm)
@param array{id: int, name: string, email?: string} $data
// 泛型
@template T
@param T $value
@return T
<?php
/**
* 用戶服務層
*
* 處理用戶註冊、認證、資料更新等核心業務邏輯。
* 整合 UserRepository、EventDispatcher、CacheManager。
*
* @package App\Services
* @subpackage User
* @author 張三 <zhang@example.com>
* @copyright 2024 Example Corp.
* @license MIT
* @since 2.0.0
*/
declare(strict_types=1);
namespace App\Services;
?>
<?php
/**
* 用戶服務
*
* 提供用戶生命週期管理功能。
*
* @property-read UserRepository $repository 僅供內部使用
* @method User findByEmail(string $email) 動態查找方法
* @implements UserServiceInterface
*/
class UserService implements UserServiceInterface {
/** @var UserRepository */
private $repository;
/** @var EventDispatcherInterface */
private $dispatcher;
/** @var CacheInterface */
private $cache;
/**
* 建構子
*
* @param UserRepository $repository
* @param EventDispatcherInterface $dispatcher
* @param CacheInterface $cache
*/
public function __construct(
UserRepository $repository,
EventDispatcherInterface $dispatcher,
CacheInterface $cache
) {
$this->repository = $repository;
$this->dispatcher = $dispatcher;
$this->cache = $cache;
}
<?php
/**
* 註冊新用戶
*
* 執行流程:
* 1. 驗證郵箱唯一性
* 2. 雜湊密碼
* 3. 建立用戶實體
* 4. 發送歡迎郵件 (非同步)
* 5. 觸發 UserRegistered 事件
*
* @param string $email 郵箱地址 (唯一)
* @param string $password 明文密碼 (最少 8 字元)
* @param string $name 顯示名稱
* @param array $attributes 額外屬性 (可選)
* @return User 新建立的用戶實體
* @throws ValidationException 參數驗證失敗
* @throws ConflictException 郵箱已存在
* @see UserRepository::create()
* @see UserRegistered
* @since 2.1.0 新增 $attributes 參數
*/
public function register(
string $email,
string $password,
string $name,
array $attributes = []
): User {
// 實現...
}
# PHPStan (推薦)
composer require --dev phpstan/phpstan
vendor/bin/phpstan analyse src --level=5
# Psalm
composer require --dev vimeo/psalm
vendor/bin/psalm --src=src
# 整合 CI
# .github/workflows/static-analysis.yml
# GitHub Actions 範例
# .github/workflows/docs.yml
name: Generate API Docs
on:
push:
branches: [main]
tags: ['v*']
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
| 檢查項 | 標準 | 工具支援 |
|---|---|---|
| 公共 API 100% 覆蓋 | 所有 public/protected 類、方法、屬性有 DocBlock | PHPStan `checkMissingIterableValueType` 等 |
| 型別宣告一致性 | PHP 8 類型宣告與 @param/@return/@var 一致 | PHPStan, Psalm, Rector |
| 無 @param 未使用參數 | 所有 @param 對應實際參數 | phpDocumentor 驗證 |
| 無 @return 缺失 | 非 void 方法必須有 @return | PHPStan `checkMissingReturnType` |
| 描述清晰度 | 摘要 < 80 字,說明「做什麼」而非「怎麼做」 | Code Review |
| 範例可執行 | @example 或說明中的代碼可直接運行 | Doctest (實驗性) |
優質的 DocBlock 註釋是**程式碼文檔化、IDE 智能提示、靜態分析、自動化文檔生成**的基石。核心原則: