【PHP8.x】DEBUG_BACKTRACE_IGNORE_ARGS定数の使い方

Copy
1<?php
2
3/**
4 * 内部関数。この関数が呼び出された際のバックトレース情報を取得し、
5 * DEBUG_BACKTRACE_IGNORE_ARGS 定数の効果を示します。
6 *
7 * @param string $param1 最初のパラメータ。
8 * @param int $param2 2番目のパラメータ。
9 */
10function innerFunction(string $param1, int $param2): void
11{
12    echo "--- 1. DEBUG_BACKTRACE_IGNORE_ARGS を指定しない場合 ---\n";
13    // DEBUG_BACKTRACE_IGNORE_ARGS を指定しない場合、
14    // debug_backtrace() の結果には関数の引数情報 (args キー) が含まれます。
15    $traceWithoutArgs = debug_backtrace();
16
17    // innerFunction のスタックフレーム (配列の最初の要素) を表示
18    echo "innerFunction のスタックフレーム:\n";
19    print_r($traceWithoutArgs[0]);
20    echo "↑ 'args' キーに引数情報 ('$param1', $param2) が含まれていることがわかります。\n\n";
21
22    echo "--- 2. DEBUG_BACKTRACE_IGNORE_ARGS を指定した場合 ---\n";
23    // DEBUG_BACKTRACE_IGNORE_ARGS 定数を指定すると、
24    // debug_backtrace() の結果から関数の引数情報 (args キー) が除外されます。
25    $traceWithIgnoreArgs = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS);
26
27    // innerFunction のスタックフレーム (配列の最初の要素) を表示
28    echo "innerFunction のスタックフレーム:\n";
29    print_r($traceWithIgnoreArgs[0]);
30    echo "↑ 'args' キーが含まれていないことがわかります。\n\n";
31}
32
33/**
34 * 外部関数。innerFunction を呼び出すことで、スタックトレースの深さを追加します。
35 *
36 * @param int $value innerFunction に渡される整数値。
37 */
38function outerFunction(int $value): void
39{
40    echo "outerFunction から innerFunction を呼び出します。\n\n";
41    innerFunction("Hello Debug", $value);
42}
43
44// スクリプトのエントリポイント
45echo "PHP 8 の DEBUG_BACKTRACE_IGNORE_ARGS 定数の動作デモ\n";
46echo "この定数は、debug_backtrace() 関数が返すバックトレース情報から、\n";
47echo "関数の引数を除外するために使用されます。\n\n";
48
49// デモ実行
50outerFunction(123);
51
52?>

PHP 8のDEBUG_BACKTRACE_IGNORE_ARGS定数は、debug_backtrace()関数が提供するバックトレース情報から、関数の引数を除外するために使用されます。この定数自体には引数や戻り値はありません。

サンプルコードでは、outerFunctionから呼び出されるinnerFunction内でdebug_backtrace()関数を2回実行し、この定数の効果を比較しています。

最初に、DEBUG_BACKTRACE_IGNORE_ARGS定数を指定せずにdebug_backtrace()を実行すると、その結果には、現在実行中のinnerFunctionに渡された引数の値が「args」というキーで含まれていることがわかります。これは、通常、関数がどのように呼び出されたかを詳細に確認したい場合に有用です。

次に、debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS)のように定数を指定して実行すると、先ほど含まれていた「args」キーが除外され、関数の引数情報が含まれていないことが確認できます。

このように、DEBUG_BACKTRACE_IGNORE_ARGS定数を使用することで、バックトレース情報を取得する際に、不要な引数情報を含めないように制御できます。これは、デバッグ時に関数名やファイル名などの情報のみが必要な場合や、引数の内容が機密情報を含むためログなどに含めたくない場合に役立つ機能です。

Copy
1<?php
2
3/**
4 * 呼び出しスタックの奥でdebug_backtrace()を実行する関数。
5 * DEBUG_BACKTRACE_IGNORE_ARGS 定数の効果を比較するために使用します。
6 *
7 * @param int $value この引数はバックトレースの引数情報に含まれるかどうかの比較対象となります。
8 */
9function deepestFunction(int $value): void
10{
11    echo "--- debug_backtrace() (引数情報を含む) ---\n";
12    // DEBUG_BACKTRACE_IGNORE_ARGS を指定しない場合
13    // 各呼び出しの引数情報が含まれて出力されます。
14    $traceWithArgs = debug_backtrace();
15    print_r($traceWithArgs);
16
17    echo "\n--- debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS) (引数情報を含まない) ---\n";
18    // DEBUG_BACKTRACE_IGNORE_ARGS を指定した場合
19    // 各呼び出しの引数情報は含まれず、メモリ消費が抑えられ、出力が簡潔になります。
20    $traceWithoutArgs = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS);
21    print_r($traceWithoutArgs);
22}
23
24/**
25 * 呼び出しスタックの中間地点の関数。
26 * 次の関数を呼び出します。
27 *
28 * @param string $message この引数はバックトレースの引数情報に含まれるかどうかの比較対象となります。
29 */
30function middleFunction(string $message): void
31{
32    // 何らかの処理をシミュレート
33    $processedMessage = strtoupper($message);
34    deepestFunction(123); // 最終的な関数を呼び出す
35}
36
37/**
38 * 呼び出しスタックの起点となる関数。
39 * 中間の関数を呼び出します。
40 *
41 * @param array $data この引数はバックトレースの引数情報に含まれるかどうかの比較対象となります。
42 */
43function startFunction(array $data): void
44{
45    // 何らかの処理をシミュレート
46    $count = count($data);
47    middleFunction("Hello PHP Developers!"); // 中間の関数を呼び出す
48}
49
50// プログラムのエントリーポイント
51// 複数の関数呼び出しを通じてバックトレースを生成します。
52startFunction(['apple', 'banana', 'cherry']);
53
54?>

PHPのdebug_backtrace()関数は、プログラムの実行中に「どこから、どのような順番で」現在の場所が呼び出されたかという履歴（バックトレース）を取得するために使用されます。

DEBUG_BACKTRACE_IGNORE_ARGSは、debug_backtrace()関数に渡すことができる定数の一つです。この定数には引数がなく、それ自体が戻り値を持ちませんが、debug_backtrace()の挙動を制御するフラグとして機能します。

具体的には、debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS)のように指定すると、取得される呼び出し履歴から、各関数が呼び出された際に渡された引数の情報が除外されます。引数情報を含まないことで、バックトレースの出力がより簡潔になり、また、メモリの使用量を抑えることができます。

サンプルコードでは、deepestFunction関数内で、引数情報を含む通常のdebug_backtrace()と、DEBUG_BACKTRACE_IGNORE_ARGSを指定したdebug_backtrace()の結果を比較しています。これにより、同じ呼び出し履歴でも、この定数を使用するかどうかで、含まれる情報の詳細度が変わることが確認できます。プログラムのデバッグ時などに、目的に応じて取得する情報の詳細レベルを選択することが可能です。