您现在的位置：程式碼之家 >> 編程語言 > >> 網頁程式設計 >> PHP 程式設計 >> PHP 相關知識

PHP 編程命名規範：類別、函數、變數、常數、錯誤處理與大括號風格統一標準

編輯：PHP 相關知識

前言

「命名是程式設計的核心」。良好的命名能讓代碼自我描述、降低認知負荷、減少文檔依賴。本文綜合 PEAR、Zend Framework、PSR-1/12、Google PHP Style Guide，制定一套落地可執行的 PHP 命名與風格規範，涵蓋類別、介面、Trait、方法、屬性、變數、常數、錯誤處理、大括號風格，並說明每條規則的理由與 IDE 配置建議。

一、類別、介面、Trait 命名

元素	規範	範例	理由
類別	StudlyCaps (大駝峰)，名詞或名詞短語	`UserService`, `OrderProcessor`	區別於函數/變數，語意清晰
介面	StudlyCaps + `Interface` 後綴	`LoggerInterface`, `CacheableInterface`	一眼識別為契約，實現類去掉後綴
Trait	StudlyCaps + `Trait` 後綴	`LoggableTrait`, `SerializableTrait`	避免與類別混淆，明確標識復用單元
抽象類	StudlyCaps + `Abstract` 前綴 (可選)	`AbstractController`	語意上區別於具體實現
異常類	StudlyCaps + `Exception` 後綴	`ValidationException`	符合 SPL 慣例，catch 時語意明確

二、方法與函數命名

慣例：camelCase (小駝峰)，動詞或動詞短語開頭。
常見前綴語意：
- get：取得值 (輕量、無副作用)
- set：設定值
- has/is/can：布林查詢
- find：查詢單筆 (可能不存在)
- search/filter：查詢集合
- create/build/make：建立新物件
- process/handle/execute：執行複雜流程
- to：轉換表示 (如 toArray())
範例：getUserById(), isEmailValid(), createOrderFromCart(), handlePaymentCallback()。

三、屬性與變數命名

類型	慣例	範例	備註
實例屬性	camelCase	`$userName`, `$dbConnection`	PSR-12 不建議底線前綴
靜態屬性	camelCase	`static $instanceCount`
區域變數	camelCase	`$totalAmount`, `$userList`
函數參數	camelCase	`function calc($basePrice, $discountRate)`
布林變數	camelCase，建議 `is`/`has`/`can` 開頭	`$isActive`, `$hasPermission`	增強可讀性
陣列變數	camelCase，複數形式	`$users`, `$orderItems`	暗示為集合

四、常數命名

慣例：全大寫，單詞用底線分隔 SNAKE_UPPER_CASE。
範疇：const、define()、global 常數、類別常數。
範例：MAX_RETRY_COUNT, DEFAULT_PAGE_SIZE, DB_TABLE_PREFIX, self::STATUS_ACTIVE。

五、錯誤處理與回傳值檢查規範

所有系統調用/外部呼叫必須檢查回傳值 (資料庫查詢、檔案操作、API 請求、fopen, curl_exec, json_decode 等)。

失敗時拋出具體異常，而非返回 false/null 讓調用者猜測。

$fp = fopen($path, 'rb');
if ($fp === false) {
    throw new RuntimeException("無法開啟檔案: $path");
}

統一錯誤訊息格式：定義錯誤代碼/訊息常數陣列或使用 gettext 國際化，避免硬編碼字串散落。

六、大括號風格 (Brace Style)

採用 **K&R 風格 (One True Brace Style)**：

<?php
if ($condition) {
    // ...
} elseif ($other) {
    // ...
} else {
    // ...
}

function foo($bar) {
    // ...
}

class Foo {
    public function bar() {
        // ...
    }
}

try {
    // ...
} catch (Exception $e) {
    // ...
}

左大括號**不換行**，與關鍵字/函數名同行，前一空格。
右大括號**獨佔一行**，與對應關鍵字/函數/類別聲明對齊。
理由：
1. 緊湊、垂直空間利用率高。
2. 編輯器「跳轉到匹配括號」功能最佳支援 (左括號在行首易定位)。
3. 主流框架 (Laravel, Symfony, PSR-12) 皆採用此風格。

特例：匿名函數作為參數時，為閱讀性可將左括號換行：

usort($arr, function ($a, $b) {
    return $a <=> $b;
});

七、IDE/工具鏈落地配置

PHP-CS-Fixer / Laravel Pint**：.php-cs-fixer.dist.php 強制執行上述規則，CI 阻擋不合規提交。
PHPStan / Psalm**：Level 5+ 靜態分析，檢測型別、未使用變數、死代碼。
PhpStorm / VS Code (PHP Intelephense)**：啟用「Code Style → PHP → Set from → PSR-12」，安裝 PHP CS Fixer 擴展存檔自動格式化。
Git Hooks (Husky / pre-commit)**：提交前自動 php-cs-fixer fix --diff。