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

Copy
1<?php
2
3/**
4 * 空のコンテナから要素を取り出そうとした際に発生する
5 * UnderflowException を処理するサンプルクラスです。
6 */
7class ContainerExample
8{
9    private array $items = [];
10
11    /**
12     * コンテナから最後の要素を取得して削除します。
13     *
14     * @return mixed
15     * @throws UnderflowException コンテナが空の場合にスローされます。
16     */
17    public function pop(): mixed
18    {
19        if (empty($this->items)) {
20            // コンテナが空の場合、エラーメッセージを指定して例外をスローします。
21            throw new UnderflowException('コンテナは空です。要素を取得できません。');
22        }
23        return array_pop($this->items);
24    }
25}
26
27// メインの処理
28$container = new ContainerExample();
29
30try {
31    // 空のコンテナから要素を取り出そうと試みます。
32    // これによりUnderflowExceptionが発生します。
33    $container->pop();
34} catch (UnderflowException $e) {
35    // catchブロックで例外を捕捉します。
36    // getMessage()メソッドで、例外がスローされた際に設定したエラーメッセージを取得できます。
37    echo "エラーを捕捉しました: " . $e->getMessage() . PHP_EOL;
38}

PHPのUnderflowException::getMessage()メソッドは、UnderflowExceptionオブジェクトが保持しているエラーメッセージを取得するためのメソッドです。このメソッドは引数を取らず、戻り値としてエラーメッセージの文字列（string）を返します。UnderflowExceptionは、空のコンテナから値を取り出そうとするなど、無効な操作が行われた際に発生する例外です。

サンプルコードでは、まずContainerExampleクラスが定義されています。その中のpopメソッドは、コンテナが空の場合に「コンテナは空です。要素を取得できません。」というメッセージを付けてUnderflowExceptionをスロー（発生）させます。

メインの処理では、try...catchブロックを使用して、この例外が発生する可能性のある処理を囲んでいます。tryブロック内で空のコンテナからpopメソッドを呼び出すと、UnderflowExceptionがスローされます。すると、プログラムはcatchブロックに処理を移し、スローされた例外オブジェクトを変数$eで捕捉します。そして$e->getMessage()を呼び出すことで、例外が生成されたときに設定されたエラーメッセージを取得し、画面に出力しています。このように、getMessage()は発生したエラーの具体的な内容を知るために重要な役割を果たします。

Copy
1<?php
2
3/**
4 * 在庫不足を表すカスタム例外クラス。
5 *
6 * PHP標準のUnderflowExceptionを継承し、より具体的なエラー情報を提供するために
7 * getMessage() メソッドをオーバーライド（override）します。
8 */
9class InventoryUnderflowException extends UnderflowException
10{
11    /**
12     * コンストラクタで、エラーが発生した商品IDを受け取ります。
13     * この構文はPHP 8のコンストラクタプロパティプロモーションです。
14     *
15     * @param string $itemId 在庫不足になった商品ID
16     * @param string $message 親クラスに渡すエラーメッセージ
17     * @param int $code エラーコード
18     * @param ?Throwable $previous 前の例外
19     */
20    public function __construct(
21        private string $itemId,
22        string $message = "",
23        int $code = 0,
24        ?Throwable $previous = null
25    ) {
26        // 親クラス(UnderflowException)のコンストラクタを呼び出します。
27        parent::__construct($message, $code, $previous);
28    }
29
30    /**
31     * 例外メッセージを取得するメソッドをオーバーライドします。
32     *
33     * 親クラスが持つ元のメッセージに、このクラス固有の情報（商品ID）を
34     * 追加して、より詳細で分かりやすいエラーメッセージを返します。
35     *
36     * @return string 整形されたエラーメッセージ
37     */
38    public function getMessage(): string
39    {
40        // parent::getMessage() で元のメッセージを取得します。
41        $originalMessage = parent::getMessage();
42        return "在庫不足エラー [商品ID: {$this->itemId}]: {$originalMessage}";
43    }
44}
45
46/**
47 * 在庫から商品を払い出す関数。
48 *
49 * @param int $currentStock 現在の在庫数
50 * @param int $quantity 払い出す数量
51 * @throws InventoryUnderflowException 在庫が要求数に満たない場合にスローされる
52 */
53function processShipment(int $currentStock, int $quantity): void
54{
55    echo "現在の在庫: {$currentStock}個、要求数: {$quantity}個\n";
56
57    if ($currentStock < $quantity) {
58        // 在庫が不足している場合、カスタム例外をスローします。
59        throw new InventoryUnderflowException('SKU-12345', "在庫が足りません。");
60    }
61
62    echo "商品を正常に払い出しました。\n";
63    // ここで実際の在庫更新処理などを行う
64}
65
66// --- 実行コード ---
67
68try {
69    // 正常なケース (例外は発生しない)
70    processShipment(10, 5);
71
72    echo "\n";
73
74    // 在庫不足を引き起こすケース (例外が発生する)
75    processShipment(10, 20);
76} catch (InventoryUnderflowException $e) {
77    // catchブロックでカスタム例外を捕捉します。
78    // $e->getMessage() を呼び出すと、オーバーライドされたメソッドが実行され、
79    // 整形されたカスタムメッセージが表示されます。
80    echo "エラーをキャッチしました。\n";
81    echo "詳細: " . $e->getMessage() . "\n";
82}

UnderflowExceptionクラスに属するgetMessage()メソッドは、例外オブジェクトに設定されたエラーメッセージを取得する際に使用します。このメソッドは引数を取らず、戻り値としてエラーメッセージの文字列（string）を返します。

このサンプルコードは、PHP標準のUnderflowExceptionを継承したInventoryUnderflowExceptionという独自の例外クラスを作成しています。この独自クラスの重要な点は、親クラスが持つgetMessage()メソッドを「オーバーライド（再定義）」していることです。

オーバーライドされたgetMessage()メソッドでは、まずparent::getMessage()を呼び出して親クラスに設定された元のエラーメッセージを取得します。次に、そのメッセージに対して、このクラス固有の情報である「商品ID」を追加し、より詳細で分かりやすい形式に整形した新しい文字列を生成して返します。

try...catchブロックでこのカスタム例外が捕捉された際、$e->getMessage()を呼び出すと、このオーバーライドされたメソッドが実行されます。その結果、単なるエラーメッセージだけでなく、原因究明に役立つ商品IDを含んだ、より具体的な情報が表示されます。このようにgetMessage()をオーバーライドすることで、アプリケーションで発生したエラーの内容をより正確に把握できるようになります。