DocBlock 結構規範
<?php
/**
* 簡短描述 (一句話摘要)
*
* 詳細描述 (可多行，說明用途、副作用、演算法、參考標準等)
*
* @category CategoryName
* @package PackageName
* @author Author Name <email@example.com>
* @copyright 2024 Company Name
* @license https://opensource.org/licenses/MIT MIT License
* @version Release: 2.3.1
* @link https://example.com/docs
* @see RelatedClass::method()
* @since 1.0.0
* @deprecated 2.0.0 Use NewClass instead
*
* @property-read string $fullName 完整姓名 (唯讀屬性)
* @property-write string $tempData 臨時數據 (唯寫屬性)
* @method void notify(string $event) 動態方法
*/
class ExampleClass
{
// ...
}
核心標籤詳細用法
| 標籤 | 適用對象 | 語法示例 | 說明 |
|---|
@param | 方法/函數 | @param string $name 用戶名
@param int[] $ids ID 列表
@param array{id:int,name:string} $user 結構化數組 (PHPStan) | 類型 變量名 描述 |
@return | 方法/函數 | @return User|null
@return iterable
@return never (永不返回) | 返回類型與說明 |
@throws | 方法/函數 | @throws ValidationException 參數驗證失敗
@throws RuntimeException 數據庫連接異常 | 異常類型與觸發條件 |
@var | 屬性/變量 | @var UserRepository
@var array | 類型推斷輔助 |
@property | 類 | @property string $name
@property-read int $id | 魔術屬性聲明 |
@method | 類 | @method static User find(int $id) | 魔術方法聲明 |
@template | 類/方法 | @template T of EntityInterface
@template-covariant T | 泛型聲明 (PHPStan/Psalm) |
@psalm- | 任意 | @psalm-suppress MixedAssignment
@psalm-pure | Psalm 專用指令 |
@phpstan- | 任意 | @phpstan-ignore-next-line
@phpstan-assert User $user | PHPStan 專用指令 |
類型表示法進階 (PHPStan/Psalm 風格)
<?php
// 聯合類型
@param string|int $id
// 可空類型
@param ?User $user
// 數組形狀
@param array{id: int, name: string, tags: string[]} $data
// 泛型
@param iterable $users
@param Collection $collection
@template T
@param T $value
@return T
// 可調用類型
@param callable(string): bool $callback
// 物件形狀
@param object{id: int, name: string} $obj
繼承與覆寫註釋
- 子類覆寫方法**必須**包含完整 DocBlock，不可僅靠繼承
- 使用
@inheritDoc 繼承父類描述，並可追加/覆蓋特定標籤
@inheritdoc (phpDocumentor) 或 @inheritDoc (Psalm) 均可
<?php
class ChildService extends ParentService
{
/**
* {@inheritDoc}
* @param UserRegistrationDto $dto 額外支援 OAuth 註冊
* @return User
* @throws OAuthException OAuth 提供商異常
*/
public function register(UserRegistrationDto $dto): User
{
// ...
}
}
自動化驗證與生成
# composer.json
"scripts": {
"phpdoc": "phpdoc -d src -t docs/api --template=clean",
"stan": "phpstan analyse src --level=5 --configuration=phpstan.neon",
"psalm": "psalm --show-info=false"
}
- PHPStan
phpdoc 規則檢查 @param/@return/@var 與代碼一致性
- Psalm
docblock 規則更嚴格，支援泛型驗證
- IDE 即時提示：PhpStorm、VS Code (PHP Intelephense) 讀取 DocBlock 提供類型推斷
