【PHP8.x】UnderflowException::messageプロパティの使い方

messageプロパティの使い方について、初心者にもわかりやすく解説します。

作成日: 2025年09月11日更新日: 2025年12月19日

基本的な使い方

『messageプロパティは、例外に関する詳細な説明文を保持するプロパティです』このプロパティは、PHPの全ての例外クラスの基底となるExceptionクラスで定義されており、UnderflowExceptionクラスもこれを継承しています。UnderflowExceptionは、例えば空のデータ構造から要素を取り出そうとするなど、コンテナが空の状態で不正な操作が行われたことを示すためにスローされる実行時例外です。例外がスローされる際、通常はコンストラクタの引数として「Cannot pop from an empty datastructure」のような具体的なエラーメッセージ文字列が渡され、その内容がこのmessageプロパティに格納されます。プログラムの実行中にこの例外をtry-catchブロックで捕捉した場合、getMessage()メソッドを呼び出すことでmessageプロパティに保存された文字列を取得できます。開発者はこの情報を利用してエラーログを記録したり、デバッグ作業を進めたりすることが可能です。このように、messageプロパティは例外が発生した具体的な原因を文字列として提供し、問題解決を助けるための重要な役割を果たします。

構文(syntax)


1<?php
2
3// 空の配列を表すスタック
4$stack = [];
5
6try {
7    if (empty($stack)) {
8        // 例外をスローする際に、コンストラクタにメッセージ文字列を渡す
9        throw new UnderflowException("コンテナが空のため、要素を取得できません。");
10    }
11} catch (UnderflowException $e) {
12    // getMessage() メソッドを介して protected な message プロパティの値を取得する
13    echo $e->getMessage();
14}
15
16?>

引数(parameters)

引数なし

引数はありません

戻り値(return)

string

このプロパティは、例外発生時の詳細なエラーメッセージを文字列として返します。

サンプルコード

PHP UnderflowExceptionメッセージ表示する


1<?php
2
3declare(strict_types=1);
4
5/**
6 * 空のコンテナから要素を削除しようとした際に発生する UnderflowException を処理し、
7 * その例外メッセージを画面に表示するサンプルです。
8 */
9class CartManager
10{
11    /**
12     * @var array<int, string> ショッピングカート内の商品リスト
13     */
14    private array $items = [];
15
16    /**
17     * カートから商品を削除します。
18     * カートが空の場合、UnderflowException をスローします。
19     *
20     * @throws UnderflowException カートが空の場合
21     */
22    public function removeItem(): void
23    {
24        if (empty($this->items)) {
25            // カートが空のときに例外を生成し、エラーメッセージを渡す
26            throw new UnderflowException("カートは空です。商品を削除できません。");
27        }
28        // 本来はここで商品を削除する処理を行う
29        array_pop($this->items);
30    }
31
32    /**
33     * 商品削除処理を実行し、結果をHTMLで表示します。
34     * 例外が発生した場合は、そのメッセージをメッセージボックス風に表示します。
35     */
36    public function displayStatus(): void
37    {
38        // Webページとして表示するためのヘッダーとスタイル
39        header('Content-Type: text/html; charset=utf-8');
40        echo <<<HTML
41<!DOCTYPE html>
42<html lang="ja">
43<head>
44    <meta charset="UTF-8">
45    <title>PHP Exception Message Example</title>
46    <style>
47        body { font-family: sans-serif; background-color: #f4f4f4; padding: 2em; }
48        .container { max-width: 600px; margin: auto; background: #fff; padding: 2em; border-radius: 8px; box-shadow: 0 2px 4px rgba(0,0,0,0.1); }
49        .message-box { border-left: 5px solid #dc3545; background-color: #f8d7da; color: #721c24; padding: 1em; margin-top: 1em; border-radius: 4px; }
50    </style>
51</head>
52<body>
53<div class="container">
54    <h2>ショッピングカート</h2>
55HTML;
56
57        try {
58            // 商品削除処理を試みる（今回は意図的に例外を発生させる）
59            $this->removeItem();
60            echo "<p>商品を削除しました。</p>"; // この行は実行されない
61        } catch (UnderflowException $e) {
62            // UnderflowException を捕捉する
63            // $e->getMessage() で、スローされた例外のメッセージ文字列を取得する
64            $errorMessage = htmlspecialchars($e->getMessage(), ENT_QUOTES, 'UTF-8');
65
66            // 取得したメッセージをHTMLのメッセージボックスとして表示する
67            echo "<div class='message-box'><strong>エラー:</strong> {$errorMessage}</div>";
68        }
69
70        echo "</div></body></html>";
71    }
72}
73
74// クラスのインスタンスを作成し、実行する
75$cartManager = new CartManager();
76$cartManager->displayStatus();

このPHPサンプルコードは、例外処理における UnderflowException の message プロパティの利用方法を解説するものです。空のショッピングカートから商品を削除しようとした際に発生するエラーを捕捉し、その内容を画面にメッセージボックスとして表示します。

UnderflowException は、空のコレクションから要素を取り出そうとするなど、不正な操作が行われたことを示すための例外です。例外を発生 (throw) させるとき、エラーの詳細を説明する文字列を渡すことができ、この文字列が message プロパティに格納されます。

このコードでは、try...catch 構文を使って例外処理を行っています。まず try ブロック内で、空のカートから商品を削除する処理を呼び出し、意図的に UnderflowException を発生させます。次に catch ブロックでその例外を捕捉します。そして、例外オブジェクトの getMessage() メソッドを呼び出すことで、message プロパティに保存されているエラーメッセージ（この例では「カートは空です。商品を削除できません。」）を取得します。getMessage() メソッドは引数を取らず、戻り値としてエラーメッセージの文字列を返します。取得したメッセージを画面に表示することで、エラーの具体的な内容をユーザーに分かりやすく通知できます。

このコードは、エラー発生時にその内容を安全に画面表示する方法を示しています。tryブロック内でエラーが発生する可能性のある処理を記述し、catchブロックでUnderflowExceptionという特定のエラーを捕捉しています。throw new UnderflowException("メッセージ")のようにして設定されたエラー文は、catchブロック内で$e->getMessage()を使って文字列として取得できます。最も重要なのは、取得したメッセージをHTMLに出力する前にhtmlspecialchars()関数でエスケープ処理している点です。この処理を怠ると、メッセージに悪意のあるコードが含まれていた場合にセキュリティ上の脆弱性となる危険があるため、必ず行うようにしてください。

PHPメッセージキューでUnderflowExceptionのmessageを取得する


1<?php
2
3declare(strict_types=1);
4
5/**
6 * シンプルなメッセージキューを表すクラス。
7 * このサンプルでは、空のキューからメッセージを取得しようとした際に発生する
8 * UnderflowException と、その 'message' プロパティの使用方法を示します。
9 */
10class SimpleMessageQueue
11{
12    /** @var array<int, string> キューに格納されたメッセージ */
13    private array $queue = [];
14
15    /**
16     * キューにメッセージを追加します（エンキュー）。
17     *
18     * @param string $message 追加するメッセージ
19     */
20    public function enqueue(string $message): void
21    {
22        $this->queue[] = $message;
23        echo "メッセージを追加しました: '{$message}'" . PHP_EOL;
24    }
25
26    /**
27     * キューからメッセージを取り出します（デキュー）。
28     *
29     * @return string 取り出したメッセージ
30     * @throws UnderflowException キューが空の場合
31     */
32    public function dequeue(): string
33    {
34        if (empty($this->queue)) {
35            // キューが空の場合、UnderflowExceptionをスローします。
36            // このときコンストラクタに渡された文字列が 'message' プロパティの値になります。
37            throw new UnderflowException('メッセージキューは空です。');
38        }
39        return array_shift($this->queue);
40    }
41}
42
43// メッセージキューのインスタンスを作成します。
44$messageQueue = new SimpleMessageQueue();
45
46try {
47    // 1. キューにメッセージを1つ追加します。
48    $messageQueue->enqueue('最初のタスク');
49
50    // 2. キューからメッセージを1つ取り出します。これは成功します。
51    $task = $messageQueue->dequeue();
52    echo "メッセージを取り出しました: '{$task}'" . PHP_EOL;
53    echo PHP_EOL;
54
55    // 3. キューは空になったので、再度取り出そうとすると例外が発生します。
56    echo '空のキューからメッセージを取り出そうとします...' . PHP_EOL;
57    $messageQueue->dequeue();
58} catch (UnderflowException $e) {
59    // 4. UnderflowExceptionを捕捉します。
60    // $e->getMessage() を使って、例外の'message'プロパティを取得し表示します。
61    echo 'エラー: ' . $e->getMessage() . PHP_EOL;
62}

PHPのUnderflowExceptionは、空のキューからデータを取り出すなど、コンテナが空の状態で値を取得しようとした際に発生するエラー（例外）の一種です。この例外オブジェクトが持つmessageプロパティは、なぜエラーが発生したのかを説明するための文字列を保持します。このプロパティに直接アクセスすることは通常なく、getMessage()というメソッドを通じて値を取得します。

サンプルコードでは、メッセージを管理するSimpleMessageQueueクラスを定義しています。dequeueメソッドは、キューが空のときにnew UnderflowException('メッセージキューは空です。')という形で例外を発生させます。このとき、コンストラクタに渡された「メッセージキューは空です。」という文字列がmessageプロパティに設定されます。

try...catchブロックでこの例外を捕捉すると、$e->getMessage()メソッドを呼び出すことができます。このメソッドは引数なしで、messageプロパティに格納されている文字列を戻り値として返します。結果として、エラーの原因となった「メッセージキューは空です。」という具体的な情報を取得し、表示することができます。このように、messageプロパティは、エラーハンドリングにおいて問題の原因を特定するために役立ちます。

このコードは、空のキューからデータを取り出そうとするとエラーが発生する例です。dequeueメソッドのように失敗する可能性のある処理は、try...catch構文で囲む必要があります。もしtry...catchがないと、エラー発生時にプログラム全体が停止してしまいます。エラーメッセージは、throw new UnderflowException('ここにメッセージを設定') のように、例外を発生させる際に指定します。catchブロックでは、受け取った例外オブジェクトのgetMessage()メソッドを呼び出すことで、この設定したメッセージを取得し、エラーの原因を具体的に知ることができます。UnderflowExceptionは、このように「中身が空の状態で何かを取り出そうとした」という特定の状況を示すための、PHPに標準で用意された例外クラスです。