PHP 程式碼品質四大支柱：安全、結構化、規範化、自適應的演進之路

前言

優良的 PHP 程式碼不只是「能跑」，更要具備安全性、結構化、規範化與自適應四大特質。本文透過三個版本的演進，展示如何從「能用」走向「專業」。

三個版本對比

❌ 版本一：未優化（高風險）

<?php
// 直接輸出使用者輸入，極度危險
echo "Search results for query: " . $_GET['query'] . "."; ?>

問題：

• XSS 漏洞：未過濾輸出，攻擊者可注入 ``
• 無輸入驗證：`$_GET['query']` 可能不存在，觸發 Notice
• 結構混亂：HTML 與 PHP 混雜，難以維護

⚠️ 版本二：簡單優化（仍有缺口）

<?php
// 僅做輸出轉義
echo "Search results for query: " . htmlspecialchars($_GET['query']) . "."; ?>

改進： 防禦 XSS（`htmlspecialchars` 轉義 HTML 實體）
遺留問題：

• 未檢查參數是否存在
• 未指定編碼與雙引號轉義旗標
• 輸出邏輯與業務邏輯耦合

✅ 版本三：合理優化（專業級）

<?php
// 1. 輸入驗證
if (isset($_GET['query'])) {
    // 2. 安全輸出：指定編碼 UTF-8、轉義雙引號 ENT_QUOTES
    echo 'Search results for query: ' 
       . htmlspecialchars($_GET['query'], ENT_QUOTES, 'UTF-8') 
       . '.';
}

亮點：

• 防禦式程式設計：`isset()` 先檢查存在性
• 完整轉義：`ENT_QUOTES` 同時轉義單雙引號，`UTF-8` 明確編碼
• 單引號字串：無變數解析，效能略優、意圖明確
• 結構清晰：驗證 → 處理 → 輸出，三階段分離

四大支柱深度解析

1. 安全性——核心原則：不信任任何輸入

2. 結構化——關注點分離

• MVC / ADR 模式：路由 → 控制器/動作 → 領域服務 → 視圖/響應
• 依賴注入：建構子注入、容器管理、介面綁定實作
• 單一職責：每個類別/函式只做一件事
• 層次化目錄：`src/Domain`、`src/Application`、`src/Infrastructure`、`src/Presentation`

3. 規範化——團隊共識即文件

• PSR-1/12：編碼風格標準（縮排、命名、括號、import 排序）
• PSR-4：自動載入對應命名空間
• 靜態分析：PHPStan Level 5+、Psalm、Rector 自動修復
• 型別宣告：嚴格模式 `declare(strict_types=1)`、回傳型別、參數型別、屬性型別
• 命名慣例：`PascalCase` 類別、`camelCase` 方法/屬性、`SCREAMING_SNAKE` 常數

4. 自適應——擁抱變化

• 設定外部化：`.env` + `vlucas/phpdotenv`，環境差異零程式碼修改
• 策略模式：支付、通訊、儲存等可替換演算法封裝為介面
• 功能開關：Feature Flag 控制新功能灰度釋出
• 向後相容：API 版本控制、DTO 轉換層、棄用標記 `@deprecated`
• 可測試性：純函式、介面依賴、Mock 友善、高覆蓋率測試

現代專案啟動清單

# composer.json 關鍵依賴
{
    "require": {
        "php": "^8.2",
        "ext-pdo": "*",
        "vlucas/phpdotenv": "^5.5",
        "monolog/monolog": "^3.4"
    },
    "require-dev": {
        "phpstan/phpstan": "^1.10",
        "psalm/plugin-phpunit": "^1.0",
        "rector/rector": "^1.0",
        "phpunit/phpunit": "^10.5",
        "friendsofphp/php-cs-fixer": "^3.40"
    },
    "scripts": {
        "analyse": ["phpstan analyse", "psalm"],
        "fix": ["rector process", "php-cs-fixer fix"],
        "test": "phpunit"
    }
}

總結

從「能跑」到「專業」，關鍵在於：

1. 安全第一：輸入驗證、輸出轉義、參數化查詢，零妥協
2. 結構清晰：分層架構、依賴注入、單一職責
3. 規範統一：PSR 標準、靜態分析、嚴格型別
4. 擁抱變化：設定外部化、策略模式、功能開關、高測試覆蓋

這四大支柱相輔相成，缺一不可。投資程式碼品質，就是投資專案的長期存活率與團隊開發效率。