FirePHP 實戰：在 Firebug/Firefox 開發者工具中調試 PHP 變量、堆棧、性能

FirePHP 讓 PHP 通過 HTTP 響應頭 (Headers) 將調試信息發送到瀏覽器開發者工具控制台，實現**不干擾頁面輸出、支援 AJAX/重定向、結構化顯示陣列/物件、堆棧追蹤、性能計時**。雖然 Firebug 已停止維護，但 FirePHP 協議被 **Chrome Logger、Firefox 開發者工具、PHPStorm、VS Code PHP Debug** 等現代工具繼承支援。本文以經典 `FirePHPCore` 庫為例，展示完整集成與進階用法。

安裝與啟用

# 1. 瀏覽器安裝插件
# Firefox: FirePHP (需 Firebug 歷史版本) 或現代替代：Chrome Logger / PHP Console
# Chrome: "Chrome Logger" 或 "PHP Console" 擴展

# 2. 服務端庫 (Composer)
composer require firephp/firephp-core
# 或手動下載 FirePHPCore/fb.php

基礎集成 (放在項目入口最早處)

<?php
// bootstrap.php / index.php 最頂部
require_once __DIR__ . '/vendor/autoload.php'; // 或 require 'FirePHPCore/fb.php'

use FirePHP\FirePHP;

// 必須在任何輸出前啟用輸出緩衝
ob_start();

// 獲取 FirePHP 實例 (單例)
$firephp = FirePHP::getInstance(true);

// 可選：開發環境啟用，生產關閉
if (($_ENV['APP_DEBUG'] ?? false) === true) {
    $firephp->setEnabled(true);
} else {
    $firephp->setEnabled(false);
}

// 可選：自定義日誌過濾器 (只記錄 WARNING 以上)
$firephp->setFilter(FirePHP::WARN);

// 可選：自定義選項
$firephp->setOptions([
    'maxObjectDepth' => 5,        // 物件最大遞歸深度
    'maxArrayDepth'  => 10,       // 陣列最大深度
    'maxSize'        => 102400,   // 單次傳輸最大字節 (超過分塊)
    'includeLineNumbers' => true, // 包含文件行號
]);
?>

核心 API 速查

實戰範例

1. 基礎變量檢視

<?php
$user = [
    'id' => 1001,
    'name' => 'Alice',
    'roles' => ['admin', 'editor'],
    'profile' => (object)['avatar' => 'a.png', 'bio' => 'Hello'],
];

fb($user);                    // 默認 LOG
fb($user, 'Current User');    // 帶標籤
fb($user, FirePHP::TABLE);    // 表格視圖 (適合平鋪陣列)
fb($user, FirePHP::INFO);     // 綠色信息
?>

2. 錯誤與異常捕獲

<?php
try {
    $pdo = new PDO('mysql:host=localhost;dbname=test', 'root', 'wrongpass');
} catch (PDOException $e) {
    fb($e, FirePHP::EXCEPTION); // 自動包含堆棧、文件、行號、錯誤碼
    // 或手動記錄錯誤上下文
    fb([
        'message' => $e->getMessage(),
        'code' => $e->getCode(),
        'file' => $e->getFile(),
        'line' => $e->getLine(),
        'trace' => $e->getTraceAsString(),
        'context' => ['dsn' => 'mysql:host=localhost;dbname=test', 'user' => 'root'],
    ], 'DB Connection Failed', FirePHP::ERROR);
}
?>

3. 性能計時與 SQL 慢查詢

<?php
$firephp = FirePHP::getInstance(true);

// 簡易計時器
$firephp->group('API Request /api/users');
$start = microtime(true);

$sql = "SELECT * FROM users WHERE status = 'active' ORDER BY created_at DESC LIMIT 20";
fb($sql, 'SQL Query', FirePHP::LOG);

$stmt = $pdo->query($sql);
$users = $stmt->fetchAll();

$duration = (microtime(true) - $start) * 1000;
fb([
    'sql' => $sql,
    'rows' => count($users),
    'duration_ms' => round($duration, 2),
    'memory_mb' => round(memory_get_peak_usage(true) / 1024 / 1024, 2),
], 'Query Profile', $duration > 100 ? FirePHP::WARN : FirePHP::INFO);

$firephp->groupEnd();
?>

4. 堆棧追蹤：定位函數被誰調用

<?php
function deepFunction($param) {
    fb($param, 'deepFunction called', FirePHP::TRACE);
    // 控制台顯示完整調用鏈：
    // deepFunction (debug.php:15)
    //   middleFunction (debug.php:10)
    //     topFunction (debug.php:5)
    //       {main} (index.php:3)
    return strtoupper($param);
}

function middleFunction($x) { return deepFunction($x); }
function topFunction($y) { return middleFunction($y); }

topFunction('test');
?>

5. 分組管理：大型請求日誌結構化

<?php
$firephp = FirePHP::getInstance(true);

$firephp->group('User Registration Flow');

fb($_POST, 'Input POST', FirePHP::LOG);

$validator = new UserValidator($_POST);
if (!$validator->isValid()) {
    fb($validator->getErrors(), 'Validation Errors', FirePHP::ERROR);
    $firephp->groupEnd();
    return;
}

fb('Validation passed', FirePHP::INFO);

$user = User::create($validator->getData());
fb($user->toArray(), 'Created User', FirePHP::INFO);

$firephp->groupEnd();
?>

現代替代方案 (Firebug 時代結束後)

生產環境安全清單

1. **嚴禁**在生產環境啟用 FirePHP/Chrome Logger (`setEnabled(false)` 或環境變量控制)。
2. 響應頭會洩露敏感數據 (SQL、用戶信息、堆棧路徑)，僅限開發/測試環境。
3. 若必須在預發環境調試，配置 IP 白名單或 HTTP Basic Auth 保護調試端點。
4. 使用 `maxSize` 限制單次傳輸體積，防止大物件導致響應頭過大被 Nginx 截斷 (`large_client_header_buffers`)。