【PHP8.x】JSON_THROW_ON_ERROR定数の使い方

Copy
1<?php
2
3/**
4 * 指定されたJSON文字列をデコードし、エラーが発生した場合は例外をスローします。
5 *
6 * この関数は `json_decode` のフラグとして `JSON_THROW_ON_ERROR` を使用し、
7 * JSONデコードエラーを捕捉可能な `JsonException` として扱います。
8 *
9 * @param string $jsonString デコードするJSON形式の文字列。
10 * @return void
11 */
12function decodeJsonWithExceptionHandling(string $jsonString): void
13{
14    echo "--- JSONデコード試行 ---\n";
15    echo "入力JSON: " . $jsonString . "\n";
16
17    try {
18        // JSON_THROW_ON_ERROR フラグを使用することで、デコードエラー時に JsonException をスローします。
19        // 第2引数を true にすると、オブジェクトは連想配列としてデコードされます。
20        $decodedData = json_decode($jsonString, true, 512, JSON_THROW_ON_ERROR);
21
22        echo "デコード成功！\n";
23        echo "結果: " . print_r($decodedData, true) . "\n";
24    } catch (JsonException $e) {
25        // JsonException を捕捉し、エラーメッセージを表示します。
26        echo "デコード失敗！エラーが発生しました。\n";
27        echo "エラーメッセージ: " . $e->getMessage() . " (コード: " . $e->getCode() . ")\n";
28    }
29
30    echo "\n";
31}
32
33// --- サンプルコードの実行 ---
34
35// 1. 正しいJSON文字列の例
36$validJson = '{"name": "Alice", "age": 30, "city": "New York"}';
37decodeJsonWithExceptionHandling($validJson);
38
39// 2. 意図的に不正なJSON文字列の例 (末尾の括弧が不足)
40$invalidJson = '{"name": "Bob", "age": 25, "city": "London"'; // 閉じ波括弧がない
41decodeJsonWithExceptionHandling($invalidJson);
42
43// 3. 別の不正なJSON文字列の例 (余分なカンマ)
44$anotherInvalidJson = '{"item": "apple", "price": 1.5, }'; // 末尾に余分なカンマ
45decodeJsonWithExceptionHandling($anotherInvalidJson);
46
47?>

PHPのJSON_THROW_ON_ERRORは、JSON文字列をデコードする際にエラー処理の挙動を制御する定数です。この定数（整数値を持ちます）をjson_decode関数のflags引数に指定すると、通常は警告となるJSONデコード時の構文エラーがJsonExceptionとしてスローされるようになります。

これにより、開発者はtry-catchブロックを用いてデコードエラーを例外として捕捉し、PHPの他の例外と同様に統一された方法でエラーハンドリングを行うことが可能になります。これは、エラーコードの確認や警告の処理に比べて、より現代的で堅牢なプログラミング手法です。

サンプルコードでは、decodeJsonWithExceptionHandling関数がJSON_THROW_ON_ERRORフラグを使用してJSONデコードを試みています。正しいJSON入力では成功してデータが表示されますが、閉じ括弧の欠如や余分なカンマがある不正なJSON入力の場合にはJsonExceptionが捕捉され、エラーメッセージが出力されることで、この定数の挙動と例外処理の有効性が具体的に示されています。システムエンジニアを目指す初心者にとって、JSON処理におけるエラーハンドリングの重要性を理解する上で役立つ例です。

Copy
1<?php
2
3/**
4 * JSON_THROW_ON_ERROR 定数の使用例を示す関数。
5 *
6 * この定数はjson_encode()やjson_decode()でJSON処理エラーが発生した場合に、
7 * 例外 (JsonException) をスローさせるために使用します。
8 * PHP 7.3以降で利用可能で、より現代的なエラーハンドリングを可能にします。
9 */
10function demonstrateJsonThrowOnError(): void
11{
12    // 不正なUTF-8バイトシーケンスを含むデータ
13    // json_encode() はこれをエンコードできず、エラーを発生させます。
14    $invalidData = [
15        'name' => 'テスト',
16        'value' => "\xB1\x31" // 無効なバイトシーケンス
17    ];
18
19    echo "--- JSON_THROW_ON_ERROR を使用しない場合 (従来のエラーチェック) ---" . PHP_EOL;
20
21    // JSON_THROW_ON_ERROR オプションなしでエンコードを試みる
22    $encodedJsonWithoutThrow = json_encode($invalidData);
23
24    if ($encodedJsonWithoutThrow === false) {
25        $errorCode = json_last_error();
26        $errorMessage = json_last_error_msg();
27        echo "JSONエンコードエラーが発生しました:" . PHP_EOL;
28        echo "  エラーコード: {$errorCode}" . PHP_EOL;
29        echo "  メッセージ: {$errorMessage}" . PHP_EOL;
30    } else {
31        echo "成功: " . $encodedJsonWithoutThrow . PHP_EOL;
32    }
33
34    echo PHP_EOL . "--- JSON_THROW_ON_ERROR を使用する場合 (例外処理) ---" . PHP_EOL;
35
36    try {
37        // JSON_THROW_ON_ERROR オプションを指定してエンコードを試みる
38        // エラーが発生すると JsonException がスローされます。
39        $encodedJsonWithThrow = json_encode($invalidData, JSON_THROW_ON_ERROR);
40        echo "成功: " . $encodedJsonWithThrow . PHP_EOL;
41    } catch (JsonException $e) {
42        // JsonException を捕捉してエラーを処理
43        echo "JSONエンコード中に例外が発生しました:" . PHP_EOL;
44        echo "  メッセージ: " . $e->getMessage() . PHP_EOL;
45        echo "  例外コード: " . $e->getCode() . PHP_EOL;
46    }
47
48    echo PHP_EOL . "--- JSON_THROW_ON_ERROR を使用した成功例 ---" . PHP_EOL;
49    $validData = [
50        'item' => '有効なデータ',
51        'quantity' => 100
52    ];
53    try {
54        $encodedValidJson = json_encode($validData, JSON_THROW_ON_ERROR);
55        echo "成功: " . $encodedValidJson . PHP_EOL;
56    } catch (JsonException $e) {
57        // この場合は例外はスローされないはずですが、一般的なtry-catchブロックとして記述
58        echo "予期せぬ例外が発生しました: " . $e->getMessage() . PHP_EOL;
59    }
60}
61
62// 関数を実行して、各ケースの動作を確認
63demonstrateJsonThrowOnError();

PHPのJSON_THROW_ON_ERRORは、JSONデータを扱う関数（主にjson_encode()やjson_decode()）のエラー処理挙動を変更するための定数です。この定数自体は整数値（int）を返しますが、直接利用するのではなく、これらのJSON処理関数のオプションとして渡すことで効果を発揮します。

PHP 7.3以降で利用でき、この定数をオプションに含めてJSON処理関数を実行すると、もしデータに問題がありエンコードやデコードが失敗した場合に、関数が単にfalseを返すのではなく、JsonExceptionという例外をスローするようになります。これにより、従来のjson_last_error()やjson_last_error_msg()といった関数でエラーコードやメッセージを確認する方法に代わり、try-catchブロックを用いた現代的で統一感のあるエラーハンドリングが可能になります。

サンプルコードでは、不正なバイトシーケンスを含むデータをエンコードする際に、この定数を使わない場合はfalseの戻り値と専用のエラー関数でエラーを検知し、使用する場合はJsonExceptionを捕捉してエラーを処理する違いを示しています。正常なデータであれば例外はスローされず、JSON文字列が正常に返されます。