現代 PHP 規範基石:PSR-12
PHP-FIG 制定的 PSR-12 (Extended Coding Style) 是目前社群公認標準,繼承 PSR-1/PSR-2。主流框架 (Laravel, Symfony, Yii) 皆遵循或擴充此規範。建議配合 PHP_CodeSniffer (phpcs) + PHP CS Fixer 自動化檢查修正。
一、檔案與基礎結構
- 編碼:UTF-8 無 BOM。
- 結尾:純 PHP 檔案**省略結尾 `?>`**,防止輸出前空白。
- 行寬:軟性 80 字元,硬性 120 字元。
- 縮排:4 空格,**禁止 Tab**。
- 換行:Unix 風格 (LF)。
二、命名慣例
| 元素 | 慣例 | 範例 |
| 類別/介面/Trait/Enum | StudlyCaps (大駝峰) | UserService, HttpClientInterface |
| 方法/函數 | camelCase (小駝峰) | getUserById, calculateTotal |
| 常量 | UPPER_SNAKE_CASE | MAX_RETRY_COUNT, DEFAULT_TIMEOUT |
| 屬性/變數 | camelCase | $userName, $orderItems |
| 私有/保護屬性/方法 | 底線前綴 + camelCase | _parseResponse, $_cache |
| 測試方法 | test + StudlyCaps | testUserCanLogin |
檔案命名對應
- 類別檔:`UserService.php` (與類別名完全一致,含大小寫)。
- 函數/腳本檔:`snake_case.php` (如 `bootstrap.php`, `helpers.php`)。
三、宣告結構
命名空間與導入
<?php
declare(strict_types=1);
namespace App\Services;
use App\Models\User;
use DateTimeImmutable;
use function count;
use const PHP_VERSION_ID;
class UserService { ... }
?>
declare(strict_types=1) 放在最頂端 (命名空間前)。
use 依序:類別、函數、常量,按字母序排序。
- 不使用前導 `\` (如 `use DateTime` 而非 `use \DateTime`)。
類別結構順序
- 常量
- 屬性 (public → protected → private)
- 建構子
- 解構子
- 魔術方法
- 公有方法
- 保護方法
- 私有方法
四、程式碼風格關鍵細節
控制結構
<?php
if ($condition) {
// ...
} elseif ($otherCondition) {
// ...
} else {
// ...
}
switch ($expr) {
case 0:
// ...
break;
default:
// ...
}
foreach ($items as $key => $value) {
// ...
}
try {
// ...
} catch (FirstException $e) {
// ...
} catch (SecondException $e) {
// ...
} finally {
// ...
}
?>
{ 放在關鍵字同行,} 獨立一行。
else, elseif, catch, finally 與前後 `}` `{` 同行。
函數/方法宣告
<?php
public function transformData(
string $input,
int $maxLength = 255,
bool $strict = false
): array {
// 型別宣告、回傳型別、預設值
// 參數過多時換行,縮排 1 層 (4 空格)
}
?>
型別宣告與嚴格模式
- **標量型別宣告** (PHP 7+):
int, float, string, bool。
- **回傳型別宣告** (PHP 7+):
: array, : ?string (可空)。
declare(strict_types=1) 僅影響**檔案內**的函數呼叫強制型別檢查。
五、常用名詞縮寫規範 (專案內統一)
| 完整單字 | 縮寫 | 適用場景 |
| identifier | id | 變數、欄位、參數 |
| number | num / no | 計數、編號 |
| maximum / minimum | max / min | 限制值 |
| configuration | config | 設定物件 |
| information | info | 資訊物件 |
| temporary | tmp | 暫存變數 |
| previous | prev | 鏈結節點 |
| current | curr | 迴圈當前項 |
原則:非通用縮寫**拼寫全名** (如 $userAuthenticationToken 不縮寫為 $uat)。
六、重構原則 (Clean Code 核心)
- 單一職責 (SRP):類別/函數只做一件事,只有一個修改理由。
- 開放封閉 (OCP):對擴充開放,對修改關閉 (介面、策略模式)。
- 函數長度:控制在 **20-30 行** 以內,超過即拆分。
- 巢狀層級:不超過 **3 層** (if/for/while),善用衛語句提早返回。
- 參數數量:不超過 **3-4 個**,超過用 DTO/Value Object 封裝。
- 死碼清除:未使用的方法、屬性、變數、import **立即刪除** (版控可追溯)。
- 註解策略:自解釋代碼優於註解。僅針對「為什麼」寫註解,「做什麼」靠命名表達。公開 API 必須有 PHPDoc。
七、自動化工具鏈 (CI/CD 整合)
# composer.json
{
"require-dev": {
"squizlabs/php_codesniffer": "^3.7",
"friendsofphp/php-cs-fixer": "^3.15"
},
"scripts": {
"cs-check": "phpcs --standard=PSR12 src/",
"cs-fix": "php-cs-fixer fix src/ --rules=@PSR12"
}
}
# 執行
composer cs-check # 檢查
composer cs-fix # 自動修正
Git Hooks (pre-commit) + CI Pipeline 強制檢查,確保團隊代碼風格一致。
結語
編碼規範非限制創意,乃**降低認知負荷、消除無意義爭辯、啟用自動化工具**的基礎設施。遵循 PSR-12 為基線,專案內建立補充規範 (如領域術語、縮寫白名單),配合靜態分析 (PHPStan Level 5+) 與測試覆蓋率門檻,打造可長期維護的高品質 PHP 代碼庫。
copyright ©
萬盛學電腦網 all rights reserved