萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP 變數命名規範最佳實務:類別、函數、屬性、變數與型別前綴

前言

統一的命名規範是團隊協作、代碼審查、自動化工具 (靜態分析、IDE) 的基礎。本文整理 PHP 社區主流慣例 (PSR-12、PHP-FIG、主流框架) 並結合型別前綴習慣,提供可直接落地的命名標準。

一、類別與介面命名

類型規範範例說明
類別PascalCase (StudlyCaps)UserService, OrderController名詞、最多 3 單詞
介面PascalCase + Interface 後綴LoggerInterface, CacheableInterface或不加後綴 (Laravel 風格)
TraitPascalCase + Trait 後綴LoggableTrait, SoftDeletesTrait
抽象類PascalCase + Abstract 前綴AbstractController可選
異常類PascalCase + Exception 後綴ValidationException
Enum (PHP 8.1+)PascalCaseStatus, UserRole

縮寫處理

// 推薦:首字母大寫,其餘小寫
HttpClient, JsonParser, ApiResponse, XmlRpc

// 不推薦:全大寫
HTTPClient, JSONParser, APIResponse

二、函數與方法命名

  • 動詞開頭:表達動作 getUser(), saveOrder(), validateInput()
  • 布林返回:is...(), has...(), can...(), should...()
  • 靜態工廠:createFrom...(), make...()
  • 避免:ErrorCheck() → checkForErrors(), DataFile() → dumpDataToFile()

三、類別屬性命名

現代趨勢:PHP 8+ 推薦不加底線前綴,靠可見性關鍵字區分,配合 IDE 色彩區分。

四、變數命名 (含型別前綴體系)

型別前綴 (Hungarian Notation 變體) 在動態語言中仍有價值,特別是缺乏型別聲明的舊代碼庫。

可見性命名風格範例
publiccamelCase$createdAt, $userName
protectedcamelCase (可選 _ 前綴)$cache, $_cache
privatecamelCase + _ 前綴 (推薦)$connection, $_eventDispatcher
staticSCREAMING_SNAKE_CASEMAX_RETRY_COUNT, DEFAULT_TIMEOUT
型別前綴範例說明
stringstr$strMessage, $strJson
array (一維)a / arr$aUsers, $arrIds單數名詞
array (多維/關聯)a / arr$aUserData, $arrConfig複數名詞
int / integern / int$nCount, $intTotal
float / doublef / flt$fPrice, $fltRate
bool / booleanb / bln$bActive, $blnEnabled
object / class instancep / obj$pUser, $objServicep 為 pointer 習慣
resourcers / res$rsConn, $resHandleDB 連線、檔案句柄
mixed / 未知mx / m$mxResult, $mData函數回傳不確定型別
callable / closurefn / cb$fnCallback, $cbHandler
null 可為空? (PHP 7.1+ 型別聲明)?string $name = null現代寫法優先

作用域前綴 (可選)

作用域前綴範例
全域變數g / g_$gConfig, $g_db
靜態變數s / s_$sInstance, $s_cache
參考/引用r / ref$rStatus, $refData
區域變數無 (純 camelCase)$userName, $totalCount

五、常數命名

// 全域常數
define('APP_VERSION', '1.0.0');
define('DB_DEFAULT_HOST', '127.0.0.1');

// 類別常數
class Config {
    public const MAX_UPLOAD_SIZE = 10 * 1024 * 1024;
    public const ALLOWED_EXTENSIONS = ['jpg', 'png', 'gif'];
}

六、綜合實例:分頁服務

pDb = $pDb;
    }
    
    public function getPageData(int $nTotal, int $nPage = 1): array {
        $nOffset = ($nPage - 1) * $this->nPerPage;
        
        // SQL 查詢
        $strSql = "SELECT * FROM users LIMIT {$nOffset}, {$this->nPerPage}";
        $rsResult = $this->pDb->query($strSql);
        
        $aRows = [];
        while ($aRow = $rsResult->fetch()) {
            $aRows[] = $aRow;
        }
        
        return [
            'items' => $aRows,
            'total' => $nTotal,
            'per_page' => $this->nPerPage,
            'current_page' => $nPage,
        ];
    }
}

// 使用範例
$pDb = new Connection('mysql:host=localhost;dbname=app', 'user', 'pass');
$pPager = new BluePage($pDb);
$nTotal = (int)$pDb->query("SELECT COUNT(*) FROM users")->fetchColumn();
$aPageData = $pPager->getPageData($nTotal, 2);

七、現代 PHP 型別系統整合 (PHP 7.4+)

優先使用型別聲明替代前綴:

// 舊式:前綴標示型別
function calculateTotal(array $aItems, float $fTaxRate): float { ... }

// 新式:型別聲明 + 清晰命名
function calculateOrderTotal(array $items, float $taxRate): float { ... }

// 屬性型別聲明
class Order {
    public int $id;
    public string $customerEmail;
    public float $totalAmount;
    public bool $isPaid;
    public ?DateTime $paidAt = null; // 可為 null
    /** @var User[] */
    public array $items = [];
}

八、工具強制規範

  • PHP_CodeSniffer + phpcs.xml (PSR-12 標準)
  • PHP-CS-Fixer 自動修復
  • Psalm / PHPStan 靜態分析 (型別檢查、命名建議)
  • IDE 設定:PhpStorm / VS Code (PHP Intelephense) 即時提示

總結

命名規範的核心目標是可讀性、可搜尋性、可維護性。現代 PHP 開發建議:

  1. 類別/方法/屬性遵循 PSR-12 (PascalCase/camelCase)
  2. 盡量使用型別聲明替代匈牙利前綴
  3. 專案內統一風格,納入 CI/CD 檢查
  4. 重構舊代碼時逐步遷移至現代規範
copyright © 萬盛學電腦網 all rights reserved