【PHP8.x】JsonException::messageプロパティの使い方
messageプロパティの使い方について、初心者にもわかりやすく解説します。
基本的な使い方
『messageプロパティは、JsonExceptionがスローされた際に、その例外に関する詳細なエラーメッセージを文字列として保持するプロパティです。このJsonExceptionは、json_encode()やjson_decode()といったJSON関連の関数で処理エラーが発生した場合に投げられます。例えば、構文が間違っているJSON文字列をデコードしようとした場合、「Syntax error」といった、人間が読んで理解できる具体的なエラー内容がこのmessageプロパティに格納されます。プログラマは、このメッセージを確認することで、エラーの根本的な原因を素早く特定し、デバッグ作業を効率的に進めることが可能になります。このプロパティはExceptionクラスから継承されたものであり、protectedとして定義されているため、通常はtry...catchブロックで例外オブジェクトを捕捉したのち、公開されているgetMessage()メソッドを通じてその値にアクセスします。このように、messageプロパティはJSON操作における堅牢なエラー処理を実装する上で不可欠な要素です。』
構文(syntax)
1<?php 2 3try { 4 json_decode("{'malformed': 'json'}", flags: JSON_THROW_ON_ERROR); 5} catch (JsonException $e) { 6 echo $e->getMessage(); 7} 8 9?>
引数(parameters)
引数なし
引数はありません
戻り値(return)
string
JsonExceptionクラスのmessageプロパティは、JSON操作中に発生したエラーメッセージを文字列で返します。
サンプルコード
PHP JsonExceptionのmessageでエラー表示
1<?php 2 3declare(strict_types=1); 4 5/** 6 * 不正なJSON文字列のデコードを試み、 7 * 発生した例外のエラーメッセージをメッセージボックス風に画面へ表示します。 8 * 9 * JsonExceptionのmessageプロパティには、json_decodeやjson_encodeで 10 * 発生したエラーの詳細な内容が文字列として格納されています。 11 * このメッセージは、Exceptionクラスから継承されたgetMessage()メソッドを通じて取得するのが一般的です。 12 */ 13function showJsonDecodeErrorMessage(): void 14{ 15 // わざと構文エラー（末尾に余分なカンマ）を含むJSON文字列を用意 16 $invalidJsonString = '{"user": "Yamada", "active": true,}'; 17 18 try { 19 // JSON_THROW_ON_ERRORオプションを指定してjson_decodeを実行 20 // このオプションにより、デコードに失敗するとJsonExceptionがスローされる 21 json_decode($invalidJsonString, true, 512, JSON_THROW_ON_ERROR); 22 } catch (JsonException $e) { 23 // JsonExceptionをキャッチし、エラーメッセージを取得する 24 $errorMessage = htmlspecialchars($e->getMessage(), ENT_QUOTES, 'UTF-8'); 25 26 // エラーメッセージをHTMLのメッセージボックスとして出力する 27 echo <<<HTML 28<!DOCTYPE html> 29<html lang="ja"> 30<head> 31 <meta charset="UTF-8"> 32 <title>JSON Error Message Box</title> 33 <style> 34 body { 35 font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; 36 display: flex; 37 justify-content: center; 38 align-items: center; 39 height: 100vh; 40 margin: 0; 41 background-color: #f0f2f5; 42 } 43 .message-box { 44 border: 1px solid #d9534f; 45 background-color: #f2dede; 46 color: #a94442; 47 padding: 20px; 48 border-radius: 8px; 49 box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1); 50 max-width: 500px; 51 } 52 .message-box h3 { 53 margin-top: 0; 54 border-bottom: 1px solid #e4b9b9; 55 padding-bottom: 10px; 56 } 57 </style> 58</head> 59<body> 60 <div class="message-box"> 61 <h3>JSONデコードエラー</h3> 62 <p>{$errorMessage}</p> 63 </div> 64</body> 65</html> 66HTML; 67 } 68} 69 70// 関数を実行してメッセージボックスを表示 71showJsonDecodeErrorMessage();
このPHPサンプルコードは、不正な形式のJSON文字列をデコードしようとした際に発生するエラーを捕捉し、その内容をメッセージボックス形式で画面に表示するものです。
PHPのjson_decode関数は、JSON_THROW_ON_ERRORオプションを指定して実行すると、デコードに失敗した際にJsonExceptionという種類の例外を発生させます。このサンプルではtry...catch構文を使い、この例外を意図的に発生させて捕捉しています。
JsonExceptionクラスは、エラーの詳細情報を持つmessageプロパティを保持しています。このプロパティの値は、親のExceptionクラスから継承されたgetMessage()メソッドを呼び出すことで取得するのが一般的です。このメソッドは引数を取らず、エラー内容を説明する文字列（string）を戻り値として返します。コード内では、catchブロックでJsonExceptionオブジェクト（変数$e）を受け取り、$e->getMessage()で具体的なエラーメッセージを取得しています。取得したメッセージは、HTMLとして安全に表示するためにhtmlspecialchars関数で処理された後、CSSで装飾されたメッセージボックス内に埋め込まれて出力されます。
json_decode関数でエラーが発生した際にJsonExceptionを発生させるには、第4引数にJSON_THROW_ON_ERRORオプションの指定が必須です。このオプションがないと例外は発生しません。例外を捕捉するためには、必ずtry...catch構文を使用してください。これがないとプログラムがエラーで停止してしまいます。JsonExceptionのエラー内容は、Exceptionクラスから継承したgetMessage()メソッドで取得するのが一般的です。また、取得したエラーメッセージをHTMLに表示する際は、クロスサイトスクリプティング（XSS）を防ぐため、htmlspecialchars関数で必ずエスケープ処理を行ってください。この処理を怠ると、セキュリティ上のリスクが生じる可能性があります。
PHPでJsonExceptionメッセージを処理する
1<?php 2 3declare(strict_types=1); 4 5/** 6 * メッセージキューから受信したメッセージを処理するクラスをシミュレートします。 7 * JSONパースエラーのハンドリングに JsonException::$message を使用します。 8 */ 9class MessageQueueProcessor 10{ 11 /** 12 * JSON形式のメッセージをデコードして処理します。 13 * 14 * 不正なJSONが渡された場合、JsonExceptionをキャッチし、 15 * その `message` プロパティを使ってエラー詳細を表示します。 16 * 17 * @param string $jsonMessage メッセージキューから受信したと想定されるJSON文字列 18 */ 19 public function process(string $jsonMessage): void 20 { 21 echo "受信メッセージ: " . $jsonMessage . PHP_EOL; 22 23 try { 24 // JSON_THROW_ON_ERRORフラグを指定し、デコード失敗時にJsonExceptionをスローさせます。 25 $data = json_decode($jsonMessage, true, 512, JSON_THROW_ON_ERROR); 26 27 // 成功した場合: デコードされたデータを使った処理を実行します（ここでは表示のみ）。 28 echo "メッセージ処理成功。ユーザーID: " . ($data['userId'] ?? '不明') . PHP_EOL; 29 30 } catch (JsonException $e) { 31 // JsonExceptionの`message`プロパティからエラーメッセージを取得し表示します。 32 // これにより、なぜJSONのデコードに失敗したのかを知ることができます。 33 echo "[エラー] メッセージ処理失敗。理由: " . $e->getMessage() . PHP_EOL; 34 } finally { 35 echo '--------------------' . PHP_EOL; 36 } 37 } 38} 39 40// === 実行コード === 41 42$processor = new MessageQueueProcessor(); 43 44// 1. 正常なJSONメッセージの処理 45$validMessage = '{"userId": 101, "action": "update_profile"}'; 46$processor->process($validMessage); 47 48// 2. 不正なJSONメッセージの処理（末尾に余分なカンマ） 49// このメッセージを処理すると JsonException がスローされます。 50$invalidMessage = '{"userId": 202, "action": "send_notification",}'; 51$processor->process($invalidMessage); 52 53?>
JsonExceptionクラスのmessageプロパティは、json_decode()やjson_encode()関数でエラーが発生した際に、その具体的な原因を説明する文字列を格納します。このプロパティを参照することで、開発者はなぜJSONの処理に失敗したのかを正確に把握でき、デバッグが容易になります。
このサンプルコードは、メッセージキューから受信したJSON文字列を処理する状況を想定しています。tryブロック内でjson_decode関数を実行し、もし渡された文字列が不正なJSON形式（例：末尾に余分なカンマがある）であった場合、JsonExceptionがスローされます。続くcatchブロックでは、発生した例外オブジェクト$eを受け取ります。そして、$e->getMessage()メソッドを呼び出すことでmessageプロパティに格納されたエラーメッセージを取得し、画面に表示しています。これにより、「Syntax error」のような具体的な失敗理由を知ることができます。
messageプロパティにアクセスする際に引数は不要です。プロパティの値として、エラー内容を示す文字列（string）が得られます。このように、messageプロパティはJSON関連のエラーハンドリングにおいて、問題の原因を特定するための重要な情報を提供します。
このコードの重要な点は、json_decode関数にJSON_THROW_ON_ERRORオプションを指定していることです。これにより、JSONの解析に失敗するとJsonExceptionという専用のエラーが発生します。try...catch構文を使ってこのエラーを捕捉することで、プログラムの異常終了を防ぎ、安全にエラー処理を行えます。catchブロックで$e->getMessage()を実行すると、PHPが生成した具体的なエラー原因（例：構文エラー）を知ることができ、デバッグが容易になります。メッセージキューのように外部からデータを受け取る際は、形式が正しいとは限らないため、このような例外処理はシステムの安定性を高める上で非常に有効です。