縮進與空白原則
- 使用 **4 空格** 縮進,**不使用 Tab** (或全專案統一 Tab)
- 每行長度建議 **≤ 120 字元**,硬性上限 80-100 字元
- 控制結構關鍵字後加一空格:
if (, for (, while (
- 函數呼叫時,函數名與左括號**無空格**:
func($arg)
- 運算子前後各一空格:
$a = $b + $c
長參數列表換行
// 推薦:參數各佔一行,縮進 1 層 (4 空格)
someMethod(
$longArgument1,
$longArgument2,
$longArgument3,
$longArgument4
);
// 巢狀呼叫
$var = someMethod1(
$longArgument1,
someMethod2(
$longArgument2,
$longArgument3
)
);
長算術/邏輯表達式換行
// 好:在運算子前換行,縮進對齊
$longName1 = $longName2 * ($longName3 + $longName4 - $longName5)
+ 4 * $longName6;
// 避免:在括號內任意換行導致層級混亂
$longName1 = $longName2 * ($longName3 + $longName4
- $longName5) + 4 * $longName6;
函數宣告換行
// 一般情況
function someMethod($arg1, $arg2, $arg3, $arg4) { ... }
// 參數過多/名稱過長:第一參數換行,縮進 1 層
function veryLongFunctionName(
$firstArgument,
$secondArgument,
$thirdArgument
) { ... }
// 避免:參數緊貼左大括號導致過深縮進
條件判斷換行
// 推薦:條件換行縮進 1 層 (4 空格),主體再縮進 1 層 (共 8 空格)
if (($condition1 && $condition2)
|| ($condition3 && $condition4)
|| !($condition5 && $condition6)) {
doSomething();
}
// 替代:條件單行,主體正常縮進
if (($condition1 && $condition2) || ($condition3 && $condition4)
|| !($condition5 && $condition6)) {
doSomething();
}
// 避免:條件無縮進,主體對齊條件導致難讀
if (($condition1 && $condition2)
|| ($condition3 && $condition4)) {
doSomething(); // 錯誤:主體未縮進
}
三元運算子格式化
// 簡單單行
$alpha = $condition ? $beta : $gamma;
// 複雜:條件換行,? : 對齊
$alpha = $longCondition
? $longTrueValue
: $longFalseValue;
// 或全部分行
$alpha = $longCondition
? $longTrueValue
: $longFalseValue;
// 避免巢狀三元 (難讀),改用 if-else
現代規範參考
- PSR-12:目前 PHP 社群主流規範 (繼承 PSR-2)
- PHP_CodeSniffer (phpcs) + PHP-CS-Fixer:自動檢查與修正
- 整合到 CI/CD:
composer require --dev squizlabs/php_codesniffer friendsofphp/php-cs-fixer
- IDE 設定自動格式化 (PHPStorm, VS Code + PHP Intelephense)
命名慣例速查
| 類型 | 慣例 | 範例 |
| 類別/介面/Enum | PascalCase | UserService, HttpClientInterface |
| 方法/函數/變數 | camelCase | getUserName, $userName |
| 常數 | UPPER_SNAKE_CASE | MAX_RETRY_COUNT |
| 私有/保護屬性 | _camelCase (慣例) | $_userName |
| 介面 | PascalCase + Interface 後綴 (可選) | LoggerInterface |
| Trait | PascalCase + Trait 後綴 | LoggableTrait |