萬盛學電腦網

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

PHP 編碼規範完整指南 (PSR-12 為核心):命名慣例、檔案結構、程式碼風格與重構原則

現代 PHP 規範基石:PSR-12

PHP-FIG 制定的 PSR-12 (Extended Coding Style) 是目前社群公認標準,繼承 PSR-1/PSR-2。主流框架 (Laravel, Symfony, Yii) 皆遵循或擴充此規範。建議配合 PHP_CodeSniffer (phpcs) + PHP CS Fixer 自動化檢查修正。

一、檔案與基礎結構

  • 編碼:UTF-8 無 BOM。
  • 結尾:純 PHP 檔案**省略結尾 `?>`**,防止輸出前空白。
  • 行寬:軟性 80 字元,硬性 120 字元。
  • 縮排:4 空格,**禁止 Tab**。
  • 換行:Unix 風格 (LF)。

二、命名慣例

元素慣例範例
類別/介面/Trait/EnumStudlyCaps (大駝峰)UserService, HttpClientInterface
方法/函數camelCase (小駝峰)getUserById, calculateTotal
常量UPPER_SNAKE_CASEMAX_RETRY_COUNT, DEFAULT_TIMEOUT
屬性/變數camelCase$userName, $orderItems
私有/保護屬性/方法底線前綴 + camelCase_parseResponse, $_cache
測試方法test + StudlyCapstestUserCanLogin

檔案命名對應

  • 類別檔:`UserService.php` (與類別名完全一致,含大小寫)。
  • 函數/腳本檔:`snake_case.php` (如 `bootstrap.php`, `helpers.php`)。

三、宣告結構

命名空間與導入

<?php
declare(strict_types=1);

namespace App\Services;

use App\Models\User;
use DateTimeImmutable;
use function count;
use const PHP_VERSION_ID;

class UserService { ... }
?>
  • declare(strict_types=1) 放在最頂端 (命名空間前)。
  • use 依序:類別、函數、常量,按字母序排序。
  • 不使用前導 `\` (如 `use DateTime` 而非 `use \DateTime`)。

類別結構順序

  1. 常量
  2. 屬性 (public → protected → private)
  3. 建構子
  4. 解構子
  5. 魔術方法
  6. 公有方法
  7. 保護方法
  8. 私有方法

四、程式碼風格關鍵細節

控制結構

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

switch ($expr) {
    case 0:
        // ...
        break;
    default:
        // ...
}

foreach ($items as $key => $value) {
    // ...
}

try {
    // ...
} catch (FirstException $e) {
    // ...
} catch (SecondException $e) {
    // ...
} finally {
    // ...
}
?>
  • { 放在關鍵字同行,} 獨立一行。
  • else, elseif, catch, finally 與前後 `}` `{` 同行。

函數/方法宣告

<?php
public function transformData(
    string $input,
    int $maxLength = 255,
    bool $strict = false
): array {
    // 型別宣告、回傳型別、預設值
    // 參數過多時換行,縮排 1 層 (4 空格)
}
?>

型別宣告與嚴格模式

  • **標量型別宣告** (PHP 7+):int, float, string, bool。
  • **回傳型別宣告** (PHP 7+):: array, : ?string (可空)。
  • declare(strict_types=1) 僅影響**檔案內**的函數呼叫強制型別檢查。

五、常用名詞縮寫規範 (專案內統一)

原則:非通用縮寫**拼寫全名** (如 $userAuthenticationToken 不縮寫為 $uat)。

六、重構原則 (Clean Code 核心)

  1. 單一職責 (SRP):類別/函數只做一件事,只有一個修改理由。
  2. 開放封閉 (OCP):對擴充開放,對修改關閉 (介面、策略模式)。
  3. 函數長度:控制在 **20-30 行** 以內,超過即拆分。
  4. 巢狀層級:不超過 **3 層** (if/for/while),善用衛語句提早返回。
  5. 參數數量:不超過 **3-4 個**,超過用 DTO/Value Object 封裝。
  6. 死碼清除:未使用的方法、屬性、變數、import **立即刪除** (版控可追溯)。
  7. 註解策略:自解釋代碼優於註解。僅針對「為什麼」寫註解,「做什麼」靠命名表達。公開 API 必須有 PHPDoc。

七、自動化工具鏈 (CI/CD 整合)

# composer.json
{
    "require-dev": {
        "squizlabs/php_codesniffer": "^3.7",
        "friendsofphp/php-cs-fixer": "^3.15"
    },
    "scripts": {
        "cs-check": "phpcs --standard=PSR12 src/",
        "cs-fix": "php-cs-fixer fix src/ --rules=@PSR12"
    }
}

# 執行
composer cs-check  # 檢查
composer cs-fix    # 自動修正

Git Hooks (pre-commit) + CI Pipeline 強制檢查,確保團隊代碼風格一致。

結語

編碼規範非限制創意,乃**降低認知負荷、消除無意義爭辯、啟用自動化工具**的基礎設施。遵循 PSR-12 為基線,專案內建立補充規範 (如領域術語、縮寫白名單),配合靜態分析 (PHPStan Level 5+) 與測試覆蓋率門檻,打造可長期維護的高品質 PHP 代碼庫。

copyright © 萬盛學電腦網 all rights reserved
完整單字縮寫適用場景
identifierid變數、欄位、參數
numbernum / no計數、編號
maximum / minimummax / min限制值
configurationconfig設定物件
informationinfo資訊物件
temporarytmp暫存變數
previousprev鏈結節點
currentcurr迴圈當前項