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

Copy
1<?php
2
3/**
4 * PHPのjson_encode関数におけるJSON_UNESCAPED_LINE_TERMINATORS
5 * および JSON_UNESCAPED_SLASHES オプションの使用例を示します。
6 *
7 * これらのオプションは、JSON出力内の特定文字のエスケープ挙動を制御します。
8 */
9function demonstrateJsonUnescapedOptions(): void
10{
11    // JSON変換するサンプルデータを用意
12    $data = [
13        'path' => 'https://example.com/api/data',
14        'message' => "これは\n複数行に\r\nわたるテキストです。",
15        'category' => 'テスト/カテゴリ',
16    ];
17
18    echo "--- デフォルトのエスケープ（オプションなし）---\n";
19    // デフォルトではスラッシュと改行文字はエスケープされます。
20    // 例: '/' は '\/'、'\n' は '\\n' になります。
21    $defaultJson = json_encode($data);
22    echo $defaultJson . "\n\n";
23
24    echo "--- JSON_UNESCAPED_SLASHES の使用 ---\n";
25    // JSON_UNESCAPED_SLASHES オプションは、スラッシュ '/' のエスケープを解除します。
26    // URLなど、スラッシュが頻繁に使われる場面でJSONをより読みやすくします。
27    $unescapedSlashesJson = json_encode($data, JSON_UNESCAPED_SLASHES);
28    echo $unescapedSlashesJson . "\n\n";
29
30    echo "--- JSON_UNESCAPED_LINE_TERMINATORS の使用 ---\n";
31    // JSON_UNESCAPED_LINE_TERMINATORS オプションは、改行文字（\n, \r）のエスケープを解除します。
32    // テキストフィールドなどに改行が含まれる場合、そのままの改行として出力されます。
33    $unescapedLineTerminatorsJson = json_encode($data, JSON_UNESCAPED_LINE_TERMINATORS);
34    echo $unescapedLineTerminatorsJson . "\n\n";
35
36    echo "--- 両方のオプションを組み合わせて使用 ---\n";
37    // 複数のオプションを同時に使用するには、ビット演算子のOR (|) を使って組み合わせます。
38    // この例では、スラッシュと改行文字の両方のエスケープが解除されます。
39    $combinedUnescapedJson = json_encode($data, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_LINE_TERMINATORS);
40    echo $combinedUnescapedJson . "\n";
41}
42
43// 関数を実行して結果を表示
44demonstrateJsonUnescapedOptions();

PHPのJSON_UNESCAPED_LINE_TERMINATORSは、json_encode関数でデータをJSON形式に変換する際に、出力されるJSON文字列の特定の文字エスケープ挙動を制御するための定数オプションです。この定数自体は引数を取らず、内部的に整数値（int）として機能します。

通常、json_encode関数は、JSONの仕様に従い、スラッシュ（/）や改行文字（\n, \r）などの特殊文字を自動的にエスケープします。例えば、スラッシュは\/に、改行は\\nのように変換されます。これはJSONの互換性を保つために重要ですが、生成されるJSON文字列が読みにくくなる場合があります。

サンプルコードは、このエスケープ挙動を制御する例を示しています。まず、オプションなしのデフォルトでは、スラッシュと改行文字がエスケープされた状態で出力されることがわかります。

次に、JSON_UNESCAPED_SLASHESオプションを使用すると、URLパスなどに含まれるスラッシュが\/のようにエスケープされず、そのまま/として出力されます。これにより、JSON内のURLなどがより自然な形で表示され、可読性が向上します。

さらに、本定数であるJSON_UNESCAPED_LINE_TERMINATORSオプションを適用すると、文字列データに含まれる改行文字（\n, \r）のエスケープが解除されます。結果として、JSON出力内でこれらの改行文字がそのまま維持され、特に複数行のテキストデータをJSONに含める場合に便利です。

複数のオプションを同時に適用したい場合は、ビットOR演算子|を使って、JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_LINE_TERMINATORSのように組み合わせることができます。これにより、スラッシュと改行文字の両方のエスケープを一度に解除できます。

これらのオプションは、生成されるJSONの可読性を高め、特定の連携システムでエスケープされていない形式が求められる場合に役立ちます。

Copy
1<?php
2
3/**
4 * PHPのJSONエンコードオプション `JSON_UNESCAPED_LINE_TERMINATORS` の使用例。
5 *
6 * この定数は、JSON文字列内の改行文字 (例: \n, \r) をエスケープせずに
7 * そのまま出力するために使用されます。PHP 8.1以降で利用可能です。
8 *
9 * `JSON_UNESCAPED_SLASHES` オプションと組み合わせることで、
10 * スラッシュ (/) もエスケープされないように設定できます。
11 */
12
13// サンプルデータを用意します。改行文字とスラッシュを含んでいます。
14$data = [
15    'title' => "ドキュメントタイトル\n次行へ",
16    'url' => 'https://example.com/path/to/resource',
17    'description' => "これは/を含む文字列です。"
18];
19
20echo "--- 1. デフォルトのjson_encodeの動作 ---\n";
21// デフォルトでは、改行文字 (\n) とスラッシュ (/) はエスケープされます。
22$jsonDefault = json_encode($data, JSON_PRETTY_PRINT);
23echo "【デフォルト】:\n" . $jsonDefault . "\n\n";
24
25echo "--- 2. JSON_UNESCAPED_LINE_TERMINATORS の使用 ---\n";
26// `JSON_UNESCAPED_LINE_TERMINATORS` を使用すると、改行文字 (\n) はエスケープされません。
27// スラッシュ (/) はデフォルトの動作（エスケープされる）のままです。
28$jsonUnescapedLineTerminators = json_encode($data, JSON_UNESCAPED_LINE_TERMINATORS | JSON_PRETTY_PRINT);
29echo "【JSON_UNESCAPED_LINE_TERMINATORS】:\n" . $jsonUnescapedLineTerminators . "\n\n";
30
31echo "--- 3. JSON_UNESCAPED_SLASHES と JSON_UNESCAPED_LINE_TERMINATORS の併用 ---\n";
32// `JSON_UNESCAPED_SLASHES` と `JSON_UNESCAPED_LINE_TERMINATORS` を併用すると、
33// スラッシュ (/) と改行文字 (\n) の両方がエスケープされなくなります。
34// 複数のオプションはビットOR演算子 (|) で結合します。
35$jsonUnescapedBoth = json_encode($data, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_LINE_TERMINATORS | JSON_PRETTY_PRINT);
36echo "【JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_LINE_TERMINATORS】:\n" . $jsonUnescapedBoth . "\n";
37

PHPのJSON_UNESCAPED_LINE_TERMINATORSは、json_encode関数でPHPのデータをJSON形式に変換する際に、文字列中の改行文字の扱いを制御するための定数です。この定数自体は引数を取らず、整数値（int）としてjson_encode関数のオプションとして利用されます。

通常、json_encode関数はJSONの標準仕様に基づき、文字列中の改行文字（例えば\nや\r）を\\nや\\rのようにエスケープして出力します。しかし、JSON_UNESCAPED_LINE_TERMINATORSをjson_encode関数の第二引数に指定すると、これらの改行文字がエスケープされずに、そのままの形でJSON文字列に含まれるようになります。これにより、生成されるJSONの可読性が向上したり、特定のシステムとの連携がスムーズになったりする場合があります。この機能はPHP 8.1以降で利用可能です。

サンプルコードでは、まずデフォルトのjson_encodeの動作として、改行文字とスラッシュがエスケープされる例が示されています。次に、JSON_UNESCAPED_LINE_TERMINATORSを指定することで、改行文字のみがエスケープされなくなることがわかります。さらに、JSON_UNESCAPED_SLASHESオプションと組み合わせると、スラッシュ（/）もエスケープせずにそのまま出力できます。複数のオプションを同時に指定したい場合は、ビットOR演算子|を使って結合することで実現できます。