PHP 除錯回溯函數 loginfo：自動捕捉呼叫位置的輕量級日誌工具

前言

開發除錯時，知道「哪裡呼叫的」比「印出什麼」更重要。PHP 的 debug_backtrace() 能獲取完整呼叫堆疊，本文封裝為 loginfo() 函數，支援 printf 風格格式化，自動記錄檔案、行號、時間，極簡易用。

核心函數

使用範例


log.txt 輸出內容
20240710 143025 /var/www/html/order.php,15: 開始處理訂單: ID=1001, 金額=99.50
20240710 143025 /var/www/html/order.php,25: 訂單 1001 處理完成
20240710 143025 /var/www/html/order.php,15: 開始處理訂單: ID=1002, 金額=-10.00
20240710 143025 /var/www/html/order.php,20: 錯誤: 金額異常 -10

進階版：支援日誌等級與多輸出
 date('Y-m-d H:i:s.u'),
            'level' => $level,
            'file'  => basename($d['file']),
            'line'  => $d['line'],
            'func'  => $d['function'] ?? '',
            'msg'   => $msg,
        ];
        
        // 預設檔案輸出
        if (self::$file) {
            file_put_contents(self::$file, json_encode($record, JSON_UNESCAPED_UNICODE) . "\n", FILE_APPEND);
        }
        
        // 自訂處理器
        foreach (self::$handlers as $h) {
            $h($record);
        }
    }
    
    public static function debug($f, ...$a) { self::log(self::DEBUG, $f, $a); }
    public static function info($f, ...$a)  { self::log(self::INFO,  $f, $a); }
    public static function warn($f, ...$a)  { self::log(self::WARN,  $f, $a); }
    public static function error($f, ...$a) { self::log(self::ERROR, $f, $a); }
}

// 使用
DebugLog::init('/var/log/myapp.log', DebugLog::INFO);
DebugLog::addHandler(function($r) {
    if ($r['level'] >= DebugLog::ERROR) {
        // 發送到 Slack/Email/鉉釘
    }
});

DebugLog::info("用戶 %s 登入", "admin");
DebugLog::error("資料庫錯誤: %s", $e->getMessage());

debug_backtrace 關鍵參數說明

  

    
參數
說明
  
  

    

      
DEBUG_BACKTRACE_PROVIDE_OBJECT
      
回傳陣列中包含 object 鍵 (當前物件)，預設不包含。設定此旗標可避免複製大型物件，節省記憶體。
    
    

      
DEBUG_BACKTRACE_IGNORE_ARGS
      
忽略函數參數資訊，大幅減少記憶體佔用與序列化時間。生產環境高頻日誌建議開啟。
    
    

      
limit (第二參數)
      
限制回傳堆疊層數。1 只取呼叫者，2 取呼叫者的呼叫者... 以此類推。
    
  


回傳陣列結構關鍵鍵值
[
    'file'     => '/path/to/file.php',      // 檔案路徑
    'line'     => 123,                      // 行號
    'function' => 'myFunction',             // 函數/方法名
    'class'    => 'MyClass',                // 類別名 (若為靜態/實例方法)
    'type'     => '->',                     // 呼叫類型: '->' 實例, '::' 靜態
    'object'   => MyClass {},               // 物件實例 (需 PROVIDE_OBJECT)
    'args'     => [...],                    // 傳入參數 (需未 IGNORE_ARGS)
]

效能建議

  
高頻路徑 (循環、每請求 > 100 次) 避免使用 debug_backtrace，改用靜態分析或編譯期注入
  
生產環境設定 DEBUG_BACKTRACE_IGNORE_ARGS 並提高日誌等級
  
大量日誌改用 Monolog + 緩衝處理器，批次寫入
  
分散式系統加入 trace_id 串聯請求鏈路


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