【PHP8.x】SodiumException::getTrace()メソッドの使い方

Copy
1<?php
2
3/**
4 * Demonstrates how to catch a SodiumException, retrieve its stack trace
5 * using `getTrace()` method, and then format that trace into a human-readable string.
6 *
7 * This function specifically targets `SodiumException` which is thrown
8 * when errors occur within the libsodium cryptography library functions.
9 * It's designed to be clear and understandable for beginners.
10 */
11function demonstrateSodiumExceptionTrace(): void
12{
13    echo "Attempting to trigger a SodiumException by providing an invalid key...\n\n";
14
15    try {
16        // sodium_crypto_box_publickey_from_secretkey expects a secret key
17        // of SODIUM_CRYPTO_BOX_SECRETKEYBYTES (typically 32 bytes).
18        // Providing an incorrect length will cause a SodiumException.
19        $invalidSecretKey = random_bytes(16); // This is only 16 bytes, not 32.
20
21        // This call will throw a SodiumException.
22        sodium_crypto_box_publickey_from_secretkey($invalidSecretKey);
23
24        // This line will not be reached if the exception is thrown.
25        echo "Public key derived successfully (unexpected outcome).\n";
26    } catch (SodiumException $e) {
27        echo "Caught a SodiumException!\n";
28        echo "Message: " . $e->getMessage() . "\n";
29        echo "File: " . $e->getFile() . "\n";
30        echo "Line: " . $e->getLine() . "\n\n";
31
32        // --- Core demonstration: getTrace() and convert to string ---
33
34        // 1. Get the raw stack trace as an array.
35        //    The `getTrace()` method returns an array, where each element
36        //    describes a step in the call stack.
37        $traceArray = $e->getTrace();
38        echo "--- Raw Trace (retrieved as array using SodiumException::getTrace()) ---\n";
39        // print_r is used here to help beginners visualize the array structure.
40        print_r($traceArray);
41        echo "--- End of Raw Trace ---\n\n";
42
43        // 2. Format the trace array into a human-readable string.
44        //    This addresses the 'php get trace as string' keyword.
45        //    We manually construct a string similar to how `Exception::getTraceAsString()` works.
46        $formattedTraceString = "--- Stack Trace (formatted as string) ---\n";
47
48        // Start with the exception itself, which is conventionally #0 in stack traces.
49        $formattedTraceString .= sprintf(
50            "#0 %s(%d): %s: %s\n",
51            $e->getFile(),
52            $e->getLine(),
53            get_class($e), // Get the class name of the exception (e.g., SodiumException)
54            $e->getMessage()
55        );
56
57        // Iterate through each step in the trace array.
58        foreach ($traceArray as $index => $step) {
59            $stepInfo = sprintf("#%d ", $index + 1); // Increment index for subsequent trace steps.
60
61            // Add file and line number if available for the current step.
62            if (isset($step['file'])) {
63                $stepInfo .= $step['file'] . '(' . $step['line'] . '): ';
64            }
65
66            // Add class and type (-> for object methods, :: for static methods) if available.
67            if (isset($step['class'])) {
68                $stepInfo .= $step['class'] . ($step['type'] ?? '->');
69            }
70
71            // Add the function name.
72            $stepInfo .= $step['function'] . '(';
73
74            // Indicate if arguments exist without exposing their potentially sensitive values
75            // or complex structures to keep the output concise for beginners.
76            if (isset($step['args']) && count($step['args']) > 0) {
77                $stepInfo .= '...';
78            }
79            $stepInfo .= ")\n";
80            $formattedTraceString .= $stepInfo;
81        }
82
83        // Add the main execution point, which is standard in PHP stack traces.
84        $formattedTraceString .= sprintf("#%d {main}\n", count($traceArray) + 1);
85
86        echo $formattedTraceString;
87        echo "--- End of Stack Trace ---\n";
88
89    } catch (Throwable $e) {
90        // Catch any other unexpected exceptions to prevent script termination.
91        echo "Caught an unexpected error: " . $e->getMessage() . "\n";
92    }
93}
94
95// Execute the demonstration function.
96demonstrateSodiumExceptionTrace();
97
98?>

PHPのSodiumException::getTrace()メソッドは、libsodium暗号化ライブラリの関数内でエラー（SodiumException）が発生した際に、その例外に至るまでの詳細な呼び出し履歴（スタックトレース）を取得するために使用されます。引数は不要で、エラー発生時の実行パスを示す連想配列の配列を返します。この配列には、各関数呼び出しのファイル名、行番号、関数名などの情報が含まれており、問題の原因を特定するデバッグ作業において非常に重要です。

サンプルコードでは、意図的に無効な鍵を使用してSodiumExceptionを発生させています。例外が捕捉されると、getTrace()メソッドでスタックトレースの配列が取得され、その内容が初心者にもわかりやすいように出力されます。さらに、この配列を加工して、通常の例外で得られるような人間が読みやすい文字列形式のスタックトレースに変換し表示する方法も具体的に示しています。これにより、エラーがプログラムのどの部分から発生し、どのような流れで現在の位置に至ったかを明確に把握でき、システムエンジニアを目指す方にとってエラー解析の強力なツールとなります。