PHP 調試工具大全：Xdebug、PHP Debug Bar、VarDumper、錯誤處理最佳實踐

現代 PHP 調試三大支柱

一、Xdebug 3.x 安裝與配置（標準流程）

1. 安裝

# Linux (PECL)
pecl install xdebug

# Windows: 下載對應 DLL (php_xdebug-3.x.x-VS16-x64.dll) 放入 ext 目錄

# Docker (推薦)
# Dockerfile
RUN pecl install xdebug && docker-php-ext-enable xdebug

2. php.ini 核心配置

[Xdebug]
zend_extension=xdebug.so  ; Windows: zend_extension=php_xdebug.dll

; 模式：debug(斷點) + develop(增強錯誤頁面) + profile(性能) + trace(跟蹤)
xdebug.mode = debug,develop

; 客戶端連接地址（IDE 監聽地址）
xdebug.client_host = 127.0.0.1
xdebug.client_port = 9003  ; Xdebug 3 默認端口

; 觸發方式：瀏覽器擴展/Bookmarklet/環境變量
xdebug.start_with_request = trigger

; 開發環境增強錯誤頁面
xdebug.var_display_max_depth = 5
xdebug.var_display_max_children = 256
xdebug.var_display_max_data = 1024

; 性能分析輸出目錄
xdebug.output_dir = /tmp/xdebug_profiler

3. IDE 配置（以 PhpStorm 為例）

1. Settings → PHP → Debug：Xdebug 端口 9003，勾選「Can accept external connections」。
2. Settings → PHP → Servers：添加項目服務器，映射本地路徑 ↔ 服務器路徑（關鍵！）。
3. 安裝瀏覽器擴展 Xdebug Helper (Chrome/Firefox/Edge)，設置 IDE Key 為 PHPSTORM。
4. 點擊擴展圖標選 Debug，刷新頁面 → PhpStorm 彈出「Incoming Connection」→ Accept → 進入斷點調試。

二、PHP Debug Bar：可視化請求調試

1. 安裝 (Composer)

composer require maximebf/debugbar

2. 原生 PHP 集成

<?php
require 'vendor/autoload.php';

use DebugBar\StandardDebugBar;
use DebugBar\DataCollector\MessagesCollector;
use DebugBar\DataCollector\PDO\PDOCollector;

$debugbar = new StandardDebugBar();
$debugbar->addCollector(new MessagesCollector('messages'));
$debugbar->addCollector(new PDOCollector($pdo, 'pdo')); // SQL 監控

// 渲染頭部資源（在 <head> 中）
echo $debugbar->getJavascriptRenderer()->renderHead();

// 業務代碼中記錄
$debugbar['messages']->info('用戶登入', ['uid' => 123]);
$debugbar['messages']->warning('緩存未命中', ['key' => 'user:123']);

// 渲染工具欄（在 </body> 前）
echo $debugbar->getJavascriptRenderer()->render();
?>

3. 框架集成

• Laravel：composer require barryvdh/laravel-debugbar --dev，自動注入工具欄。
• Symfony：composer require --dev maximebf/debugbar，配置 DebugBarBundle。
• ThinkPHP：composer require maximebf/debugbar，中間件注入。

三、VarDumper：告別 var_dump

1. 安裝

composer require symfony/var-dumper

2. 使用

<?php
require 'vendor/autoload.php';

use Symfony\Component\VarDumper\VarDumper;

$user = [
    'id' => 1,
    'name' => '張三',
    'roles' => ['admin', 'editor'],
    'created_at' => new DateTime('2023-01-15'),
    'metadata' => null
];

// 替代 var_dump/print_r
VarDumper::dump($user);
// 或全局 helper (需在入口引入 dump.php)
dump($user); // 更短

// 輸出特點：
// 🎨 顏色高亮類型（字符串綠、數字藍、null 灰、對象黃）
// 📂 可摺疊嵌套結構
// 🔍 支持搜索、複製路徑
// 🌐 瀏覽器控制台/HTML 雙模式自適應
?>

3. 進階：Caster 自定義對象輸出

<?php
use Symfony\Component\VarDumper\Cloner\VarCloner;
use Symfony\Component\VarDumper\Dumper\HtmlDumper;

$cloner = new VarCloner();
// 為 Eloquent 模型添加自定義輸出（隱藏遞歸關係、只顯示核心屬性）
$cloner->addCasters([
    'Illuminate\Database\Eloquent\Model' => function ($model, $array, $stub, $isNested) {
        return array_filter($array, fn($k) => !in_array($k, ['relations', 'connection']), ARRAY_FILTER_USE_KEY);
    }
]);

$dumper = new HtmlDumper();
$dumper->dump($cloner->cloneVar($user));
?>

四、錯誤與異常處理最佳實踐

1. 開發環境：顯示所有錯誤

<?php
// 入口文件最頂部
error_reporting(E_ALL);
ini_set('display_errors', '1');
ini_set('display_startup_errors', '1');

// 可選：Whoops 友好錯誤頁面
// composer require filp/whoops
$whoops = new \Whoops\Run();
$whoops->pushHandler(new \Whoops\Handler\PrettyPageHandler());
$whoops->register();
?>

2. 生產環境：記錄不顯示、友好錯誤頁

<?php
error_reporting(E_ALL & ~E_DEPRECATED & ~E_STRICT); // 生產建議
ini_set('display_errors', '0');
ini_set('log_errors', '1');
ini_set('error_log', '/var/log/php/error.log');

// 自定義異常處理器
set_exception_handler(function (Throwable $e) {
    // 記錄日誌
    error_log(sprintf(
        "[%s] %s in %s:%d\nStack:\n%s",
        date('c'),
        $e->getMessage(),
        $e->getFile(),
        $e->getLine(),
        $e->getTraceAsString()
    ));
    
    // 返回友好響應
    if (php_sapi_name() === 'cli') {
        echo "Error: {$e->getMessage()}\n";
        exit(1);
    }
    
    http_response_code(500);
    header('Content-Type: text/html; charset=utf-8');
    echo '<h1>系統維護中，請稍後再試</h1>';
    // 或渲染模板：include __DIR__ . '/templates/500.php';
});

set_error_handler(function ($severity, $message, $file, $line) {
    if (!(error_reporting() & $severity)) return false; // 未在報告範圍內
    throw new ErrorException($message, 0, $severity, $file, $line);
});

五、調試工作流建議

1. 新功能開發：Xdebug 斷點調試 → 理解流程、驗證邏輯。
2. API 聯調：VarDumper dump($request->all()) + Debug Bar 查看 SQL/緩存。
3. 性能優化：Xdebug Profile 模式生成 cachegrind.out.*，用 QCacheGrind/WebGrind 分析熱點函數。
4. 線上問題排查：日誌系統 + 錯誤追蹤，嚴禁生產環境開啟 Xdebug/Debug Bar/VarDumper 輸出。

總結

• Xdebug 是專業斷點調試與性能分析的「重型武器」，配置稍繁但能力最強。
• PHP Debug Bar 是開發環境的「儀表盤」，零侵入式查看 SQL、請求數據、緩存命中。
• VarDumper 是日常變量檢查的「輕量利器」，一行代碼替換 var_dump，體驗質變。
• 錯誤處理：開發環境全開、生產環境全記錄+友好頁，統一用 set_exception_handler/set_error_handler。