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

Copy
1<?php
2
3/**
4 * PHPのJSON処理におけるJSON_UNESCAPED_UNICODE定数の使用例を示します。
5 * この定数は json_encode() 関数に渡すオプションで、マルチバイト文字（例: 日本語）を
6 * \uXXXX の形式でエスケープせずに、そのままの文字でJSON文字列に出力します。
7 * また、エンコードされたJSON文字列を json_decode() でPHPのデータに変換する例も示します。
8 */
9function demonstrateJsonUnescapedUnicode(): void
10{
11    // 日本語を含む連想配列を準備
12    $data = [
13        'name' => '山田 太郎',
14        'email' => 'yamada@example.com',
15        'city' => '東京都',
16        'message' => 'こんにちは、PHPの世界へようこそ！'
17    ];
18
19    echo "--- JSON_UNESCAPED_UNICODE オプションなしでエンコードした場合 ---" . PHP_EOL;
20    // オプションなしの場合、日本語などのマルチバイト文字は \uXXXX 形式でエスケープされる
21    $jsonEncodedDefault = json_encode($data);
22    echo "結果: " . $jsonEncodedDefault . PHP_EOL . PHP_EOL;
23
24    echo "--- JSON_UNESCAPED_UNICODE オプション付きでエンコードした場合 ---" . PHP_EOL;
25    // JSON_UNESCAPED_UNICODE を使用すると、マルチバイト文字がエスケープされずにそのまま出力される
26    $jsonEncodedUnescaped = json_encode($data, JSON_UNESCAPED_UNICODE);
27    echo "結果: " . $jsonEncodedUnescaped . PHP_EOL . PHP_EOL;
28
29    echo "--- json_decode() を使用してデコードする場合 ---" . PHP_EOL;
30    // エスケープされていないJSON文字列を json_decode() でPHPのデータに変換
31    // json_decode() は、JSON文字列がエスケープされていてもされていなくても、正しくデコードします。
32    $decodedData = json_decode($jsonEncodedUnescaped, true); // true を指定すると連想配列としてデコード
33    echo "デコードされたデータ (name): " . ($decodedData['name'] ?? 'N/A') . PHP_EOL;
34    echo "デコードされたデータ (message): " . ($decodedData['message'] ?? 'N/A') . PHP_EOL;
35}
36
37// 関数の実行
38demonstrateJsonUnescapedUnicode();

PHPのJSON_UNESCAPED_UNICODEは、PHP 8で利用できるJSON関連の拡張機能に属する定数です。この定数自体は引数を持たず、json_encode()関数のオプションとして使用される整数値を表します。

主な用途は、PHPのデータ（配列やオブジェクト）をJSON文字列に変換するjson_encode()関数において、日本語などのマルチバイト文字が\uXXXX形式（ユニコードエスケープシーケンス）でエスケープされるのを抑制することです。通常、json_encode()はマルチバイト文字をエスケープしますが、JSON_UNESCAPED_UNICODEオプションを指定することで、文字がそのままの形でJSON文字列に出力されます。これにより、生成されるJSON文字列が人間にとって読みやすくなります。

例えば、日本語の文字列を含む配列をjson_encode()で変換する際にこのオプションを使わないと、日本語はエスケープされた形式で出力されますが、このオプションを使うと「山田 太郎」のような元の文字で出力されます。

一方、json_decode()関数は、JSON文字列をPHPのデータ形式（連想配列やオブジェクト）に変換する関数です。json_decode()は、JSON_UNESCAPED_UNICODEオプションの有無にかかわらず、エスケープされたJSON文字列も、エスケープされていないJSON文字列も、どちらも正しく元のPHPのデータ構造にデコードすることができます。

Copy
1<?php
2
3// PHPの連想配列を準備します。このデータに日本語を含めます。
4// この配列がJSONに変換される元のデータとなります。
5$data = [
6    'id' => 101,
7    'name' => '山田 太郎',
8    'email' => 'yamada@example.com',
9    'message' => 'こんにちは、PHPからのJSONデータです！',
10    'products' => [
11        ['product_id' => 1, 'product_name' => 'コーヒー'],
12        ['product_id' => 2, 'product_name' => '紅茶']
13    ]
14];
15
16// json_encode関数を使用して、PHPのデータをJSON形式の文字列に変換します。
17// 第二引数には、JSON生成のオプションをビットマスクで指定します。
18//
19// JSON_UNESCAPED_UNICODE (PHP 5.4.0以降):
20//   日本語などのUnicode文字が '\uXXXX' の形式にエスケープされず、
21//   そのままの文字でJSONに出力されます。これにより、JSONが読みやすくなります。
22//
23// JSON_PRETTY_PRINT (PHP 5.4.0以降):
24//   生成されるJSON文字列を見やすいように、インデントと改行を加えて整形します。
25//   デバッグや人間が読み取る際に非常に便利です。
26$jsonString = json_encode(
27    $data,
28    JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT
29);
30
31// json_encodeが失敗した場合（例: エンコード不可能なデータが含まれる場合）はfalseを返します。
32if ($jsonString === false) {
33    echo "JSONエンコードに失敗しました。\n";
34    // どのようなエラーが発生したかを確認できます。
35    echo "エラーメッセージ: " . json_last_error_msg() . "\n";
36} else {
37    // 正常に変換されたJSON文字列を出力します。
38    echo $jsonString;
39}
40
41?>

このサンプルコードは、PHPのデータをJSON形式の文字列に変換する方法を示しています。まず、日本語の文字を含むPHPの連想配列$dataを用意します。これは、JSONとして出力される元のデータとなります。

次に、json_encode関数を使用して、このPHP配列をJSON形式の文字列に変換します。この関数の第二引数には、JSONの生成に関するオプションを整数値で指定します。ここで使用されているJSON_UNESCAPED_UNICODEとJSON_PRETTY_PRINTは、PHP 5.4.0以降で利用可能な定数です。

JSON_UNESCAPED_UNICODEは整数値を持ち、日本語などのUnicode文字がJSON出力時に\uXXXXのようなエスケープ形式ではなく、そのままの文字で表示されるように指示するオプションです。これにより、生成されるJSONが人間にとって読みやすくなります。一方、JSON_PRETTY_PRINTも整数値を持ち、JSON文字列にインデントと改行を加えて、より整形された見やすい形式で出力するオプションです。これら二つの定数は、ビット論理和演算子|を使って組み合わせることで、同時に適用できます。

json_encode関数は、変換に成功するとJSON形式の文字列を返しますが、失敗した場合はfalseを返します。サンプルコードでは、この戻り値を確認し、失敗した場合にはエラーメッセージも出力するようにしています。最終的に、成功した場合は整形されたJSON文字列が画面に表示されます。