PHP 編碼規範指南：從新手到高手的進階之路

空格規則

• 控制結構關鍵字後加空格：if (, foreach (
• 運算子前後加空格：$a = $b + $c;
• 函式呼叫無空格：foo($bar)
• 陣列短語法：[$a, $b]、['key' => $val]
• 類型宣告：function foo(int $bar): string

PHP 標籤

• 純 PHP 檔案**省略結束標籤** ?>
• 開頭 <?php 獨佔一行，後接空行

命名規範

禁用拼音命名：$yongHuMing ❌ → $userName ✅

註解規範

檔案標頭

<?php
/**
 * 使用者服務類
 *
 * @package App\Services
 * @author  Team Name
 * @since   2024-01-01
 */

函式/方法 DocBlock

/**
 * 依 ID 取得使用者
 *
 * @param int $id 使用者 ID
 * @return User|null 使用者物件，不存在回傳 null
 * @throws UserNotFoundException 找不到時拋出（可選策略）
 */
public function getById(int $id): ?User
{
    // ...
}

行內註解

• 單行：// 理由說明 放在程式碼上方
• 避免廢話註解：$i++; // i 加 1
• TODO/FIXMARK 標準化：// TODO: 支援多語系

函式設計原則

• **單一職責**：一個函式只做一件事
• **規模控制**：≤ 50 行（不含註解/空行）
• **參數數量**：≤ 3 個，超過用 DTO/陣列/物件
• **回傳型別**：盡可能宣告，避免混合回傳
• **避免副作用**：純函式易測試、易推理

流程控制

• 優先 foreach 遍歷陣列
• switch 每個 case 以 break 結尾，或註解 // no break
• 三元運算子僅用於簡單賦值，巢狀禁用
• else if 寫成 elseif（單字）

字串與陣列

• 單引號字串不解析變數，**優先使用**
• 雙引號需用 {$var} 包裹變數
• 陣列鍵名**必須加引號**：$arr['key'] 而非 $arr[key]
• 字串連接：$a . ' ' . $b 兩側加空格

錯誤處理

• 使用 try-catch 處理例外，避免 @ 抑制錯誤
• 自訂例外繼承 Exception 或 \DomainException
• 輸入驗證：isset()/empty()/filter_var()
• 資源管理：try-finally 或 using 模式關閉連線/檔案

SQL 規範

• 關鍵字大寫：SELECT, FROM, WHERE
• 明確列出欄位，**禁用 SELECT ***
• 參數綁定：**嚴禁字串拼接 SQL**
• 表名/欄位名用反引號：\`users\`
• 使用 LIMIT 避免全表掃描

工具整合

# composer.json
"require-dev": {
    "phpcs/php-cs-fixer": "^3.0",
    "phpstan/phpstan": "^1.10",
    "psalm/plugin-phpunit": "^0.16"
}

# 執行
./vendor/bin/php-cs-fixer fix --rules=@PSR12
./vendor/bin/phpstan analyse src
./vendor/bin/psalm --show-info=false

Git Hooks 自動化