Xdebug 代碼覆蓋分析全攻略：配置、API 與實戰範例

Xdebug 代碼覆蓋分析完整指南

代碼覆蓋率是衡量測試完整性的關鍵指標。Xdebug 提供強大的內建函數與配置選項，能精確記錄腳本執行過哪些行、哪些分支未被觸達。本文系統整理相關設定、核心 API 及實戰用法。

一、核心配置選項

二、核心函數 API

1. xdebug_code_coverage_started() → bool

檢查覆蓋率收集是否已啟動。

<?php
var_dump(xdebug_code_coverage_started()); // bool(false)
xdebug_start_code_coverage();
var_dump(xdebug_code_coverage_started()); // bool(true)
?>

2. xdebug_start_code_coverage(int $options = 0) → void

啟動收集。回傳二維陣列：[檔案名][行號] = 值。

行值含義：

• 1：該行已執行
• -1：可執行但未執行 (需啟用 XDEBUG_CC_UNUSED)
• -2：無可執行代碼 (需同時啟用 XDEBUG_CC_UNUSED + XDEBUG_CC_DEAD_CODE)

選項常數：

• XDEBUG_CC_UNUSED：分析哪些行屬「可執行但未執行」
• XDEBUG_CC_DEAD_CODE：進一步偵測永遠不會被執行的死代碼

啟用範例：

<?php
xdebug_start_code_coverage(XDEBUG_CC_UNUSED | XDEBUG_CC_DEAD_CODE);
// ... 執行業務邏輯 ...
?>

注意：開啟選項會顯著降低分析速度，僅建議開發/測試環境使用。

3. xdebug_get_code_coverage() → array

取得目前收集到的覆蓋率資料結構。

<?php
xdebug_start_code_coverage();
function a($a) { echo $a * 2.5; }
function b($count) {
    for ($i = 0; $i < $count; $i++) {
        a($i + 0.17);
    }
}
b(6);
b(10);
var_dump(xdebug_get_code_coverage());
?>

輸出範例：

array(
  '/path/to/file.php' => array(
    5 => 1, 6 => 1, 7 => 1,
    9 => 1, 10 => 1, 11 => 1, 12 => 1, 13 => 1,
    15 => 1, 16 => 1, 18 => 1
  )
)

4. xdebug_stop_code_coverage(bool $cleanup = true) → void

停止收集。$cleanup=true (預設) 會清除記憶體資料；傳 false 可保留資料，後續再次呼叫 xdebug_start_code_coverage() 可續收。

三、實戰整合建議

1. 單元測試框架整合：PHPUnit 內建 --coverage-html 即基於 Xdebug 此組 API，無需手動呼叫。
2. 自訂報表：若需自製儀表板，可在測試套件 bootstrap 階段呼叫 xdebug_start_code_coverage()，測試結束前取資料生成 JSON/HTML 報表。
3. 效能考量：生產環境務必設 xdebug.coverage_enable=0；開發機僅在跑測試時啟用。

四、常見問題排查

• 資料為空：確認 xdebug.coverage_enable=1 且在執行目標代碼 前 呼叫 xdebug_start_code_coverage()。
• 行號偏移：OPcache 優化可能導致行號對應失真，測試環境建議關閉 OPcache 或設 opcache.optimization_level=0。
• 記憶體爆增：大型專案收集全專案覆蓋率會佔用大量記憶體，可用 XDEBUG_CC_UNUSED 按需開啟，或針對特定目錄收集。