PHP 除錯日誌工具類：自動記錄呼叫位置與上下文資訊

前言

開發過程中，良好的日誌系統能大幅提升除錯效率。本文介紹兩款 PHP 除錯日誌工具：一個是物件導向的 Tool::log() 靜態類，另一個是函數式的 loginfo()。兩者都能自動捕捉呼叫者的檔案、行號、類別、方法等上下文資訊，免去手動傳遞位置參數的麻煩。

方案一：Tool 靜態類 (物件導向風格)

b(); }
    public function b() { $this->c(); }
    public function c() { Tool::log('sdfsdf'); }
}

$action = new Action();
$action->a();

輸出範例

07-10 14:30:25 /test.php:25 Action->c: sdfsdf

方案二：loginfo() 函數 (函數式風格，更輕量)

使用範例


輸出範例
20240710 143025 /var/www/html/order.php,42: 用戶 admin 登入，IP: 192.168.1.100
20240710 143026 /var/www/html/order.php,55: 訂單 12345 建立，金額: 99.50

進階增強：支援日誌等級與多輸出
 date('Y-m-d H:i:s.u'),
            'level'   => $level,
            'file'    => $d['file'],
            'line'    => $d['line'],
            'class'   => $d['class'] ?? '',
            'func'    => $d['function'],
            'message' => $msg,
        ];
        
        foreach (self::$handlers as $handler) {
            $handler($record);
        }
    }
    
    // 便利方法
    public static function debug($fmt, ...$args) { self::log(self::DEBUG, $fmt, ...$args); }
    public static function info($fmt, ...$args)  { self::log(self::INFO,  $fmt, ...$args); }
    public static function warn($fmt, ...$args)  { self::log(self::WARN,  $fmt, ...$args); }
    public static function error($fmt, ...$args) { self::log(self::ERROR, $fmt, ...$args); }
}

// 註冊處理器：檔案 + 錯誤級別發送 Email
Logger::addHandler(function($r) {
    file_put_contents(__DIR__.'/app.log', json_encode($r, JSON_UNESCAPED_UNICODE)."\n", FILE_APPEND);
});
Logger::addHandler(function($r) {
    if ($r['level'] >= Logger::ERROR) {
        mail('admin@example.com', '[ERROR] '.$r['message'], json_encode($r));
    }
});

// 使用
Logger::info("用戶 %s 登入", "admin");
Logger::error("資料庫連線失敗: %s", $e->getMessage());

效能考量與最佳實踐

  

    
場景
建議
  
  

    

      
高頻呼叫 (循環、每請求上百次)
      
避免每次 file_put_contents；使用緩衝、批次寫入或專用日誌庫 (Monolog)
    
    

      
生產環境
      
設定適當日誌等級、啟用日誌輪轉 (logrotate)、避免記錄敏感資料
    
    

      
分散式系統
      
加入 trace_id 串聯請求鏈路、結構化日誌 (JSON)、集中收集 (ELK/Loki)
    
    

      
除錯回溯
      
debug_backtrace() 有效能開銷；高頻路徑可快取或簡化
    
  


推薦成熟方案：Monolog
實際專案建議直接使用 Monolog，它是 PHP 事實標準的日誌庫，支援：

  
多種處理器：檔案、Syslog、Slack、Email、MongoDB、Elasticsearch 等
  
日誌等級、格式化器、處理器鏈
  
PSR-3 介面相容，易於整合 Laravel、Symfony 等框架
  
日誌輪轉、指尖處理器 (只在錯誤時發送完整堆疊)


pushHandler(new RotatingFileHandler(__DIR__.'/logs/app.log', 30, Logger::DEBUG));

$log->info('用戶登入', ['user' => 'admin', 'ip' => '192.168.1.1']);
$log->error('支付失敗', ['order_id' => 123, 'error' => $e->getMessage()]);

延伸閱讀
更多 PHP 相關內容可參考本站專題：《PHP 錯誤與異常處理方法總結》、《PHP 字符串用法總結》、《PHP 陣列操作技巧大全》、《PHP 運算與運算符用法總結》、《PHP 網絡編程技巧總結》、《PHP 基本語法入門教程》、《PHP 面向對象程序設計入門教程》、《PHP+MySQL 數據庫操作入門教程》及《PHP 常見數據庫操作技巧匯總》。