Zenn
🐘

debug_backtrace の使い方

に公開
PHP
tech

debug_backtrace() の使い方

debug_backtrace() は、PHP で現在の関数呼び出しに至るまでの「コールスタック（関数やメソッドの呼び出し履歴）」を取得するためのデバッグ用関数です。エラーの原因特定や、関数がどこから呼ばれたかを調べる際に役立ちます。

基本的な使い方

function third() {
    // バックトレースを取得し表示
    $backtrace = debug_backtrace();
    foreach ($backtrace as $index => $call) {
        echo "#{$index} {$call['function']}() ";
        if (isset($call['file'])) {
            echo "呼び出し元: {$call['file']}";
            if (isset($call['line'])) {
                echo " 行: {$call['line']}";
            }
        }
        echo "\n";
    }
}

function second() { third(); }
function first() { second(); }

first();

この例では、first() → second() → third() の順に呼ばれ、third() 内でバックトレースを取得して表示しています。

返される情報

キー 説明
function 現在の関数名
line 現在の行番号
file 現在のファイル名
class 現在のクラス名（メソッドの場合）
object 現在のオブジェクト（メソッドの場合）
type 呼び出しタイプ（-> や :: など）
args 関数に渡された引数の配列

オプションと制限

  • options（第一引数）
    例: DEBUG_BACKTRACE_PROVIDE_OBJECT（オブジェクト情報を含む）、DEBUG_BACKTRACE_IGNORE_ARGS（引数情報を除外）など。
  • limit（第二引数）
    取得するスタックフレームの数を制限できます。デフォルトは全件。

例:

// 引数情報を除外し、最新2件のみ取得
$backtrace = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 2);

実践的な使い方

  • エラー箇所の特定
    エラーや不具合が発生した箇所の呼び出し元をトレースする。
  • ログ出力
    ログファイルにバックトレースを出力し、後から原因を調査する。
  • デバッグツール作成
    独自のデバッグ関数内で利用し、呼び出し元や引数を表示する。

注意点

  • オブジェクトや大量の引数がある場合、バックトレースが大きくなりすぎることがあります。必要に応じてオプションや制限を活用してください。
  • 本番環境ではパフォーマンスやセキュリティの観点から、出力内容やログレベルに注意してください。

debug_backtrace() の array の順番について

debug_backtrace() が返す配列（array）は「連想配列の配列」です。つまり、各要素が1つのスタックフレーム（関数呼び出し単位の情報）を表しており、配列の添字（インデックス）が小さいほど「現在の呼び出しに近い（深い）」、大きいほど「スタックの上の方（呼び出し元、浅い）」の情報になります。

順番の具体例

function third() {
    var_dump(debug_backtrace());
}
function second() { third(); }
function first() { second(); }
first();

この場合、debug_backtrace() の出力配列は以下のような順番になります。

  1. 0番目: third() の呼び出し元（second() 内で呼ばれた情報）
  2. 1番目: second() の呼び出し元（first() 内で呼ばれた情報）
  3. 2番目: first() の呼び出し元（グローバルスコープや別ファイルなど）

つまり、配列の先頭（0番）が直近の呼び出し元、末尾が一番最初の呼び出し元です。

まとめ表

インデックス 内容
0 直近の呼び出し元
1 その1つ前
... ...
n 一番最初の呼び出し元

この順番で、どの関数からどの関数が呼ばれたか（コールスタック）を上から順番に追うことができます。

参考例（var_dump 出力イメージ）

array(3) {
  [0] => array(...) // second() 内で third() を呼んだ情報
  [1] => array(...) // first() 内で second() を呼んだ情報
  [2] => array(...) // グローバルで first() を呼んだ情報
}

このように、配列の順番は「深い呼び出しから浅い呼び出し」 への流れとなります。

まとめ

debug_backtrace() は、PHPのデバッグ時に「関数がどこから呼ばれたか」「どの順番で実行されたか」を調べるための強力なツールです。オプションや制限を活用して、効率的にデバッグを行いましょう。

Discussion