PHP 開發編碼規範指南（PSR-12 為核心的團隊落地版）

前言

統一編碼風格能降低認知負擔、減少合併衝突、提升代碼可讀性。本指南以 PSR-12 為基準，結合 PHP 社群慣例與團隊實踐，給出可直接落地的規範清單。

1. 基礎格式

• 縮排：4 個空格，禁用 Tab。
• 行長：軟限制 120 字元，硬限制不可超過。
• 編碼：UTF-8 無 BOM。
• 行尾：LF (Unix)。
• 檔案結尾：保留一空行。
• 純 PHP 檔案省略 ?> 結束標籤。

2. 命名規範

3. 宣告與關鍵字

• class/interface/trait 名稱後同行左大括號 {，右大括號 } 獨立一行。
• extends/implements 同行；過長換行縮排 1 層。
• 屬性必須宣告可見性（public/protected/private），不可用 var。
• 方法必須宣告可見性，static/final/abstract 置於可見性之後。
• 參數列表：左括號不換行，逗號後加空格，右括號與左大括號同行。
• 嚴格型別宣告：declare(strict_types=1); 置於檔案最頂端。

4. 控制結構

• if/elseif/else/while/for/foreach/switch/try/catch 關鍵字後加一空格，左括號同行，右大括號獨立行。
• else/elseif/catch/finally 與前一右大括號同行。
• 條件判斷過長：換行縮排 1 層，邏輯運算符置於行首。

5. 陣列與字串

• 短陣列語法 []，元素逗號後加空格，多行時尾隨逗號。
• 雙引號字串僅用於插值/逸出序列，其餘用單引號。
• Heredoc/Nowdoc 用於長字串/模板，結束標記頂格。

6. 註解與文檔

• 類別、公共方法、介面必須有 PHPDoc 區塊（/** ... */）。
• @param、@return、@throws 標籤完整；型別用 PHPDoc 標準（string[], User|null）。
• 行內註解 // 前後各一空格，獨立行置於代碼上方。

7. 錯誤處理

• 拋出具體例外類別（繼承 Exception 或 RuntimeException）。
• 捕獲例外時按具體類別處理，避免 catch (Exception $e) 吞噬錯誤。
• 資源釋放用 try/finally 或 using 模式（PHP 8.1+ fclose 等已支援）。

8. 測試與靜態分析

• 單元測試覆蓋率 ≥ 80%（核心業務 100%）。
• CI 流程整合 PHPStan Level 5+、Psalm、PHP_CodeSniffer (phpcs)。
• Git Hook（pre-commit）自動執行 phpcs --standard=PSR12、phpstan analyse。

9. 專案結構建議

src/
  Domain/         # 核心業務邏輯、實體、值物件
  Application/    # 用例服務、DTO、命令/查詢處理器
  Infrastructure/ # 資料庫、快取、外部 API 適配器
  Presentation/   # HTTP 控制器、中介軟體、視圖模型
tests/
  Unit/
  Integration/

10. 工具鏈一鍵修正

# 安裝
composer require --dev squizlabs/php_codesniffer phpstan/phpstan vimeo/psalm

# 檢查
vendor/bin/phpcs --standard=PSR12 src/
vendor/bin/phpstan analyse src/ --level=5
vendor/bin/psalm --show-info=true

# 自動修正大多數風格問題
vendor/bin/phpcbf --standard=PSR12 src/

結語

規範是為了人，不是為了工具。團隊共同制定、持續優化、工具強制執行，才能真正發揮效用。新成員入職第一天跑通 phpcbf，養成「提交前自動修正」肌肉記憶。