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

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * 空のスタックから要素を取り出そうとする状況をシミュレートするクラス。
7 */
8class SafeStack
9{
10    /**
11     * @var array<int, mixed> スタックの要素を保持する配列
12     */
13    private array $elements = [];
14
15    /**
16     * スタックから要素を取り出します。
17     *
18     * @return mixed 取り出した要素
19     * @throws UnderflowException スタックが空の場合にスローされます
20     */
21    public function pop(): mixed
22    {
23        if (count($this->elements) === 0) {
24            // スタックが空の状態でpopを試みたため、UnderflowExceptionをスローします。
25            // UnderflowExceptionは、無効な操作（例: 空のコンテナからのデータ取得）を
26            // 行おうとした際に発生する実行時エラーの一種です。
27            throw new UnderflowException('スタックから要素を取り出すことはできません。スタックは空です。');
28        }
29        return array_pop($this->elements);
30    }
31}
32
33/**
34 * スタック処理を実行し、例外を発生させる関数。
35 *
36 * @param SafeStack $stack 操作対象のスタック
37 */
38function processStack(SafeStack $stack): void
39{
40    echo "スタックから要素を取り出そうとしています...\n";
41    // この呼び出しでUnderflowExceptionが発生します。
42    $stack->pop();
43}
44
45/**
46 * アプリケーションのメイン処理。
47 */
48function main(): void
49{
50    $stack = new SafeStack();
51    // 例外を発生させる関数を呼び出します。
52    processStack($stack);
53}
54
55// メイン処理を実行します。
56try {
57    main();
58} catch (UnderflowException $e) {
59    // UnderflowExceptionを捕捉します。
60    echo "\nエラーが発生しました: " . $e->getMessage() . "\n\n";
61
62    // getTraceAsString()メソッドは、例外が発生した時点までの
63    // 関数の呼び出し履歴（スタックトレース）を文字列として返します。
64    // デバッグ時に、どこで、どのような順序で関数が呼ばれてエラーに至ったかを確認するのに役立ちます。
65    echo "--- スタックトレース (getTraceAsString) ---\n";
66    echo $e->getTraceAsString();
67    echo "\n----------------------------------------\n";
68}
69
70?>

このPHPサンプルコードは、例外処理で使用される UnderflowException クラスの getTraceAsString() メソッドの動作を示しています。UnderflowException は、空のスタックのようなコンテナからデータを取り出そうとするなど、不可能な操作が行われた際に発生する実行時エラーの一種です。

コードでは、空のデータ構造である SafeStack クラスを定義し、そのインスタンスから pop() メソッドで要素を取り出そうとします。スタックが空のため、pop() メソッドは UnderflowException を意図的にスロー（発生）させます。

プログラムのメイン処理は try-catch ブロックで囲まれており、スローされた UnderflowException を捕捉します。catch ブロック内で呼び出されている $e->getTraceAsString() は、例外が発生するまでの関数の呼び出し履歴、すなわち「スタックトレース」を文字列として取得するメソッドです。このメソッドは引数を取らず、戻り値としてスタックトレース情報を含む文字列を返します。この文字列を確認することで、どのファイルの何行目で、どの関数がどのような順序で呼び出された結果エラーに至ったのかを正確に追跡でき、プログラムのデバッグに役立ちます。