PHP 編碼規範（二）：文件頭註釋、修改記錄與版權聲明標準

文件頭標準註釋模板

<?php
/**
 * UserService.php
 *
 * 用戶業務邏輯服務層，提供註冊、認證、資料更新等核心功能
 *
 * @package    App\Service
 * @author     Zhang San <zhangsan@example.com>
 * @copyright  2024 Example Corp.
 * @license    MIT
 * @version    2.1.0
 * @since      2023-05-15
 * @link       https://github.com/example/project
 */

必要標籤說明

修改記錄區塊

在文件頭註釋末尾或單獨區塊記錄重要變更：

/**
 * ...
 * @changelog
 * 2024-03-10 v2.1.0 Zhang San: 新增 OAuth2 綁定功能 (Issue #456)
 * 2024-01-22 v2.0.5 Li Si: 修復密碼重置 Token 重複使用漏洞 (CVE-2024-xxxx)
 * 2023-11-01 v2.0.0 Wang Wu: 重構為服務層架構，引入 Repository 模式
 */

行內修改標記（小範圍變更）

<?php
// ... 原代碼 ...

// === MODIFIED 2024-03-10 by Zhang San: Issue #456 新增 OAuth2 綁定 ===
public function bindOAuth(string $provider, string $accessToken): User
{
    // 新增邏輯...
}
// === END MODIFIED ===

// ... 後續代碼 ...

版權聲明最佳實踐

1. 項目根目錄放置 LICENSE 文件（MIT/Apache-2.0/GPL-3.0 等）
2. 每個源文件頭部包含 @copyright 與 @license 標籤
3. 若為專有代碼，使用 @license Proprietary 並註明「All rights reserved」
4. 第三方庫保留原作者版權頭，不可移除

自動化檢查

• PHP_CodeSniffer 規則集 PSR12 包含文件頭檢查
• Git pre-commit hook 集成 phpcs --standard=PSR12
• CI 流水線階段運行 phpcs 阻斷不合規提交