PHPer 必知的 11 大編程規範：從新手到專業的進階之路

前言：代碼規範不是束縛，是自由的基石

良好的代碼規範能降低認知負荷、減少 Bug、提升團隊協作效率、便於重構與維護。本文梳理 11 項 PHP 開發核心規範，結合現代工具鏈 (PHP_CodeSniffer, PHP-CS-Fixer, Psalm, PHPStan, Rector) 落地執行，助你寫出專業級代碼。

1. 錯誤報告分級策略：開發全開、生產零容忍

// 開發環境：顯示所有錯誤，嚴格模式
error_reporting(E_ALL);
ini_set('display_errors', '1');
ini_set('log_errors', '1');
ini_set('error_log', '/var/log/php/error.log');

// 生產環境：不顯示，只記錄，關閉嚴格標準提示
error_reporting(E_ALL & ~E_DEPRECATED & ~E_STRICT);
ini_set('display_errors', '0');
ini_set('log_errors', '1');

現代最佳實踐： 使用 php -d error_reporting=E_ALL 啟動內建伺服器；框架 (Laravel/Symfony) 已內建優異的異常處理與日誌系統，遵循框架配置即可。

2. DRY 原則：不要重複你自己

WET (Write Everything Twice) 是技術債的溫床。

// ❌ WET：硬編碼散落各處
$pdo = new PDO('mysql:host=localhost;dbname=shop', 'root', 'secret');
$pdo2 = new PDO('mysql:host=localhost;dbname=shop', 'root', 'secret');

// ✅ DRY：配置集中、依賴注入、單例/容器管理
// config/database.php
return [
    'default' => 'mysql',
    'connections' => [
        'mysql' => [
            'host' => env('DB_HOST', '127.0.0.1'),
            'database' => env('DB_DATABASE', 'shop'),
            'username' => env('DB_USERNAME', 'root'),
            'password' => env('DB_PASSWORD', ''),
        ],
    ],
];

// 使用 Laravel 服務容器自動解析
$users = DB::table('users')->get();

3. 縮進、空格與編碼風格：遵循 PSR-12

• 縮進： 4 空格 (非 Tab)，declare(strict_types=1); 頂行。
• 行長： 軟限制 120 字符，硬限制不超過 80 推薦。
• 大括號： 類/方法/控制結構 下一行 開啟 (Allman 風格)，else/elseif/catch/finally 與大括號同行。
• 關鍵字： true/false/null 小寫；類型聲明、返回類型緊貼冒號 function foo(): int。

工具強制統一：

# 安裝
composer require --dev squizlabs/php_codesniffer friendsofphp/php-cs-fixer

# 檢查 (PSR-12)
./vendor/bin/phpcs --standard=PSR12 src/

# 自動修復
./vendor/bin/php-cs-fixer fix src/ --rules=@PSR12

4. 命名規範：語義清晰、風格統一

5. 扁平化代碼：拒絕箭頭型嵌套

守衛子句 早期返回 是消除深層嵌套的核心技巧：

// ❌ 箭頭代碼：難讀、難測、難維護
function processOrder(Order $order): bool {
    if ($order->isValid()) {
        if ($order->hasStock()) {
            if ($payment->charge($order->total)) {
                if ($inventory->reserve($order->items)) {
                    $order->confirm();
                    return true;
                }
            }
        }
    }
    return false;
}

// ✅ 守衛子句：線性閱讀、單一職責
function processOrder(Order $order): bool {
    if (!$order->isValid()) return false;
    if (!$order->hasStock()) return false;
    if (!$payment->charge($order->total)) return false;
    if (!$inventory->reserve($order->items)) return false;
    
    $order->confirm();
    return true;
}

6. 文檔註釋：PHPDoc 標準 + 類型聲明雙重保障

/**
 * 根據用戶 ID 獲取訂單列表
 *
 * @param int $userId 用戶 ID
 * @param int $limit  最大筆數
 * @param int $offset 偏移量
 * @return Order[] 訂單集合
 * @throws RepositoryException 查詢失敗
 */
public function getOrdersByUserId(int $userId, int $limit = 20, int $offset = 0): array
{
    // PHP 8.0+ 可直接用返回類型 array (需 phpstan/phpdoc 擴展)
    return $this->orderRepository->findByUser($userId, $limit, $offset);
}

工具： phpstan 靜態分析檢查 PHPDoc 與代碼一致性；rector 自動補全/升級類型聲明。

7. 敏感資訊隔離：絕不提交 .env 到版本庫

• .env 只存在於本地/部署伺服器，.env.example 提交作為模板。
• 生產環境密鑰透過 CI/CD 密鑰管理 (GitHub Secrets, GitLab CI Variables, Vault) 注入。
• phpinfo()、var_dump($GLOBALS) 等調試代碼嚴禁 進入生產代碼庫。

8. 零信任輸入：驗證、過濾、語境編碼三重奏

// 1. 輸入驗證 (表單請求 / DTO)
class StoreUserRequest extends FormRequest {
    public function rules(): array {
        return [
            'email' => 'required|email|unique:users,email',
            'age' => 'required|integer|between:18,120',
            'bio' => 'nullable|string|max:500',
        ];
    }
}

// 2. 業務層再次防禦 (值物件/實體建構子驗證)
class Email {
    public function __construct(private string $value) {
        if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
            throw new InvalidArgumentException("Invalid email: $value");
        }
    }
}

// 3. 輸出語境編碼 (Blade/Twig 自動逃逸、API 輸出 JSON)
{{ $user->bio }} {{-- Blade 自動 htmlentities --}}
echo json_encode($data, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);

9. 快取策略：多層次、按需失效、監控命中率

關鍵： 快取鍵設計包含版本/租戶/語言；寫入時失效 (Cache Aside 模式)；監控 hit_rate 低於 80% 需優化。

10. 變數管理：拒絕無意義複製、善用解構

// ❌ 無意義複製
$desc = strip_tags($_POST['description']);
echo $desc;

// ✅ 直接使用、解構賦值 (PHP 7.1+)
echo strip_tags($_POST['description'] ?? '');

// ✅ 批量解構
['email' => $email, 'name' => $name] = $validatedData;
// 或物件屬性提升 (PHP 8.0+)
public function __construct(
    private string $email,
    private string $name,
) {}

11. 框架選型與架構治理：站在巨人肩膀上

• Laravel： 生態最豐富、開發效率最高、適合中大型應用、SaaS、電商。
• Symfony： 企業級、高度解耦、長期維護、複雜領域模型、微服務基礎。
• API Platform： 基於 Symfony，零代碼生成 GraphQL/REST API、Admin 介面。
• Slim / Lumen (維護模式) / Flight： 輕量微服務、中間件管道。

架構原則： 領域驅動設計 (DDD) 分層 —— Domain (核心業務) → Application (用例/命令/查詢) → Infrastructure (資料庫/外部 API/框架) → Interface (HTTP/CLI/Queue)。依賴反轉 讓核心業務不依賴框架。

工具鏈一鍵落地 (composer scripts 範例)

{
    "scripts": {
        "cs-check": "phpcs --standard=PSR12 src/",
        "cs-fix": "php-cs-fixer fix src/ --rules=@PSR12",
        "stan": "phpstan analyse src/ --level=max",
        "psalm": "psalm --show-info=false",
        "test": "phpunit",
        "ci": [
            "@cs-check",
            "@stan",
            "@psalm",
            "@test"
        ]
    },
    "require-dev": {
        "squizlabs/php_codesniffer": "^3.7",
        "friendsofphp/php-cs-fixer": "^3.15",
        "phpstan/phpstan": "^1.10",
        "vimeo/psalm": "^5.15",
        "phpunit/phpunit": "^10.0"
    }
}

執行 composer ci 即可在 CI/CD 流水線中強制代碼品質門檻。

總結

規範不是目的，可維護性、可擴展性、團隊協作效率 才是。從今天開始：

1. 引入 PHP_CodeSniffer + PHP-CS-Fixer 統一風格。
2. 開啟 declare(strict_types=1); + PHPStan Level 5+ 靜態分析。
3. 重構嵌套為守衛子句，提煉小函數，賦予語義命名。
4. 建立代碼審查 (Code Review) 文化，規範在審查中沉澱演進。

好代碼像好文章，讓人一眼看懂意圖，十年後依然優雅。