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

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * シンプルなスタック（後入れ先出し）データ構造を表すクラス。
7 * このクラスは、コンストラクタを持つ例外クラスの使用例を示します。
8 */
9class SimpleStack
10{
11    /** @var array<int, mixed> スタックの要素を保持する配列 */
12    private array $items = [];
13
14    /**
15     * スタックに要素を追加します (プッシュ)。
16     *
17     * @param mixed $item 追加する要素
18     */
19    public function push(mixed $item): void
20    {
21        $this->items[] = $item;
22    }
23
24    /**
25     * スタックから要素を取り出します (ポップ)。
26     *
27     * @return mixed スタックの最後の要素
28     * @throws UnderflowException スタックが空の場合
29     */
30    public function pop(): mixed
31    {
32        // スタックが空かどうかをチェックします。
33        if (empty($this->items)) {
34            // スタックが空の場合、UnderflowExceptionのインスタンスを生成してスローします。
35            // ここで UnderflowException::__construct() が呼び出され、
36            // 引数にエラーメッセージとエラーコードが渡されます。
37            throw new UnderflowException('Cannot pop an item from an empty stack.', 1001);
38        }
39
40        // 配列の最後の要素を取り出して返します。
41        return array_pop($this->items);
42    }
43}
44
45// スタックのインスタンスを作成します。
46$stack = new SimpleStack();
47
48try {
49    // 最初に要素を追加します。
50    $stack->push('First item');
51    echo "Popped: " . $stack->pop() . "\n";
52
53    // 次に、空になったスタックから意図的に要素を取り出そうとします。
54    // これにより、pop()メソッド内でUnderflowExceptionがスローされます。
55    echo "Attempting to pop from an empty stack...\n";
56    $stack->pop();
57} catch (UnderflowException $e) {
58    // スローされたUnderflowExceptionを捕捉します。
59    echo "\nSuccessfully caught an exception!\n";
60    echo "-----------------------------------\n";
61    echo "Exception Type: " . get_class($e) . "\n";
62
63    // コンストラクタで設定したメッセージを取得して表示します。
64    echo "Message: " . $e->getMessage() . "\n";
65
66    // コンストラクタで設定したコードを取得して表示します。
67    echo "Code: " . $e->getCode() . "\n";
68    echo "File: " . $e->getFile() . "\n";
69    echo "Line: " . $e->getLine() . "\n";
70}

UnderflowException::__constructは、UnderflowExceptionクラスの新しいインスタンスを生成する際に自動的に呼び出される、コンストラクタという特別なメソッドです。このメソッドの主な役割は、生成される例外オブジェクトが持つべき情報、例えばエラーメッセージやエラーコードなどを初期化することです。

このコンストラクタは3つの引数を取ります。第1引数$messageには、例外の具体的な理由を示すエラーメッセージの文字列を渡します。第2引数$codeには、エラーの種類を識別するための整数値を設定します。第3引数$previousは、この例外の前に別の例外が発生した場合に、その例外を関連付けるために使います。

サンプルコードのpop()メソッドでは、スタックが空の状態で要素を取り出そうとすると、throw new UnderflowException(...)が実行されます。ここでコンストラクタが呼び出され、第1引数にエラーメッセージ、第2引数にエラーコード1001が設定された例外オブジェクトが生成されます。catchブロックでは、$e->getMessage()や$e->getCode()を使い、コンストラクタで設定された値を取得して表示しています。コンストラクタはオブジェクトの初期化が目的のため、特定の戻り値はありません。

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * 空のコンテナから要素を取り出そうとした場合に発生する
7 * UnderflowException の使用例を示すためのシンプルなスタッククラス。
8 */
9final class SimpleStack
10{
11    /** @var array<int, mixed> スタックデータを保持する配列 */
12    private array $stack = [];
13
14    /**
15     * スタックに要素を追加します。
16     *
17     * @param mixed $item 追加する要素
18     */
19    public function push(mixed $item): void
20    {
21        $this->stack[] = $item;
22        echo "Pushed: " . $item . PHP_EOL;
23    }
24
25    /**
26     * スタックから要素を取り出します。
27     *
28     * @return mixed 取り出した要素
29     * @throws UnderflowException スタックが空の場合
30     */
31    public function pop(): mixed
32    {
33        if (empty($this->stack)) {
34            // スタックが空の状態でpopを試みたため、例外をスローします。
35            // ここで UnderflowException のコンストラクタ (__construct) が呼び出され、
36            // 例外メッセージが設定されます。
37            throw new UnderflowException('Cannot pop from an empty stack.');
38        }
39
40        $item = array_pop($this->stack);
41        echo "Popped: " . $item . PHP_EOL;
42        return $item;
43    }
44}
45
46$stack = new SimpleStack();
47
48try {
49    // 正常な処理: 要素を追加して取り出す
50    $stack->push('Apple');
51    $stack->push('Banana');
52    $stack->pop(); // Banana
53    $stack->pop(); // Apple
54
55    echo '---' . PHP_EOL;
56
57    // 例外が発生する処理: 空のスタックから取り出そうとする
58    echo 'Trying to pop from an empty stack...' . PHP_EOL;
59    $stack->pop();
60
61} catch (UnderflowException $e) {
62    // スローされた UnderflowException を捕捉し、メッセージとコードを表示する
63    echo 'Caught exception: ' . $e->getMessage() . PHP_EOL;
64    echo 'Exception Code: ' . $e->getCode() . PHP_EOL;
65}

UnderflowException::__constructは、UnderflowExceptionクラスの新しいオブジェクトを生成する際に呼び出されるコンストラクタです。この例外は、空のコンテナから要素を取り出そうとするなど、無効な操作が行われたことを示すために使用されます。

サンプルコードでは、スタックが空の時にpopメソッドが呼ばれると、new UnderflowException(...)という形でこのコンストラクタが実行され、例外オブジェクトが生成・スローされます。

コンストラクタには3つの引数を指定できます。第1引数$messageには、例外の理由を説明する文字列を設定します。サンプルでは'Cannot pop from an empty stack.'が渡され、catchブロックで$e->getMessage()により取得されています。第2引数$codeには、エラーを識別するための整数値を設定でき、$e->getCode()で取得します。省略した場合は0になります。第3引数$previousは、この例外の前に発生した別の例外を関連付けるために使いますが、通常は省略されます。

コンストラクタはオブジェクトを初期化する役割を持つため、特定の値を返すことはなく、戻り値はありません。