PHP Tips | 文字列処理：入力補助 － 配列 → JSON（pretty）

何をしたいユーティリティなのか

「配列 → JSON（pretty）」は、 PHP の配列や連想配列を「人間が読みやすい JSON 文字列」に変換するユーティリティです。

普通の json_encode だと、こうなります。

["apple","orange","banana"]

["apple","orange","banana"]

でも「pretty（整形）」を使うと、こうなります。

[
    "apple",
    "orange",
    "banana"
]

インデントや改行が入るので、 ログに出したり、画面に表示したり、設定ファイルとして保存したりするときに、 「中身が一目で分かる」形になります。

JSON と PHP 配列の関係をざっくり理解する

連想配列は JSON オブジェクトになる

PHP の連想配列は、JSON では「オブジェクト」として表現されます。

$data = [
    'id'   => 123,
    'name' => 'Taro',
    'tags' => ['php', 'backend'],
];

$data = [
    'id'   => 123,
    'name' => 'Taro',
    'tags' => ['php', 'backend'],
];

これを JSON にすると、こうなります。

{
    "id": 123,
    "name": "Taro",
    "tags": [
        "php",
        "backend"
    ]
}

「キー → 値」の構造がそのまま JSON に変換されるイメージです。

インデックス配列は JSON 配列になる

インデックス配列（0,1,2…の連番キー）は、JSON では「配列」として表現されます。

$items = ['apple', 'orange', 'banana'];

$items = ['apple', 'orange', 'banana'];

これを JSON にすると、こうです。

[
    "apple",
    "orange",
    "banana"
]

PHP の配列は「連想配列とインデックス配列の両方」を兼ねているので、 JSON にするときは「キーの形」によってオブジェクトか配列かが決まります。

コアとなる「pretty JSON」ユーティリティを作る

json_encode にフラグを付けるだけで pretty になる

PHP の json_encode には、整形用のフラグがあります。

• JSON_PRETTY_PRINT … インデントと改行を付ける
• JSON_UNESCAPED_UNICODE … 日本語を \uXXXX にせず、そのまま出す
• JSON_UNESCAPED_SLASHES … / を \/ にせず、そのまま出す

これらを組み合わせると、「人間が読みやすい JSON」が簡単に作れます。

function to_pretty_json(mixed $value): string
{
    $json = json_encode(
        $value,
        JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES
    );

    // 失敗した場合は空文字を返す（実務ではログなども推奨）
    if ($json === false) {
        return '';
    }

    return $json;
}

function to_pretty_json(mixed $value): string
{
    $json = json_encode(
        $value,
        JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES
    );

    // 失敗した場合は空文字を返す（実務ではログなども推奨）
    if ($json === false) {
        return '';
    }

    return $json;
}

ここでの重要ポイントは、

JSON_PRETTY_PRINT でインデントと改行が付くこと。 JSON_UNESCAPED_UNICODE で日本語がそのまま読めること。 JSON_UNESCAPED_SLASHES で URL などが見やすくなること。

この 3 つをセットで覚えておくと、pretty JSON はほぼ完成です。

例題で挙動を確認する

シンプルな配列

$items = ['apple', 'orange', 'banana'];

echo to_pretty_json($items);

$items = ['apple', 'orange', 'banana'];

echo to_pretty_json($items);

出力はこうです。

[
    "apple",
    "orange",
    "banana"
]

インデントが付いていて、 「何番目に何が入っているか」が一目で分かります。

連想配列＋ネスト

$data = [
    'id'   => 123,
    'name' => '山田太郎',
    'tags' => ['php', 'backend'],
    'meta' => [
        'active' => true,
        'score'  => 98.5,
    ],
];

echo to_pretty_json($data);

$data = [
    'id'   => 123,
    'name' => '山田太郎',
    'tags' => ['php', 'backend'],
    'meta' => [
        'active' => true,
        'score'  => 98.5,
    ],
];

echo to_pretty_json($data);

出力はこうです。

{
    "id": 123,
    "name": "山田太郎",
    "tags": [
        "php",
        "backend"
    ],
    "meta": {
        "active": true,
        "score": 98.5
    }
}

ネストした構造も、インデントのおかげでとても読みやすくなっています。 日本語もそのまま表示されているので、ログや画面でも違和感がありません。

実務での使いどころ

デバッグログに「構造付きの情報」を残したいとき

外部 API に送るペイロードや、 ユーザーの設定情報などをログに残したいとき、 pretty JSON はかなり便利です。

$payload = [
    'user_id' => 123,
    'action'  => 'login',
    'roles'   => ['admin', 'editor'],
];

error_log("payload=\n" . to_pretty_json($payload));

$payload = [
    'user_id' => 123,
    'action'  => 'login',
    'roles'   => ['admin', 'editor'],
];

error_log("payload=\n" . to_pretty_json($payload));

ログには、例えばこう出ます。

payload=
{
    "user_id": 123,
    "action": "login",
    "roles": [
        "admin",
        "editor"
    ]
}

「どんな構造のデータを送ったか」が一目で分かるので、 後から原因を追うときにとても役立ちます。

管理画面で JSON を編集させたいとき

設定を JSON で持っていて、 管理画面で「その JSON を直接編集できるようにしたい」ケースもあります。

$config = [
    'featureA' => true,
    'featureB' => false,
    'limits'   => [
        'max_users' => 100,
        'max_logs'  => 10000,
    ],
];

$valueForTextarea = to_pretty_json($config);

// <textarea><?= htmlspecialchars($valueForTextarea, ENT_QUOTES, 'UTF-8') ?></textarea>

$config = [
    'featureA' => true,
    'featureB' => false,
    'limits'   => [
        'max_users' => 100,
        'max_logs'  => 10000,
    ],
];

$valueForTextarea = to_pretty_json($config);

// <textarea><?= htmlspecialchars($valueForTextarea, ENT_QUOTES, 'UTF-8') ?></textarea>

pretty JSON にしておけば、 管理者が見ても「どの項目が何を意味しているか」が分かりやすくなります。

失敗時の扱いをどうするか

json_encode が false を返すケース

json_encode は、 循環参照があるオブジェクトなどを渡すと失敗して false を返すことがあります。

実務では、「失敗したら空文字を返す」だけでなく、 「ログにエラーを残す」「例外を投げる」などの対応も検討したほうがいいです。

例えば、もう少し真面目な版はこうです。

function to_pretty_json_or_throw(mixed $value): string
{
    $json = json_encode(
        $value,
        JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES
    );

    if ($json === false) {
        throw new RuntimeException('JSON encode failed: ' . json_last_error_msg());
    }

    return $json;
}

function to_pretty_json_or_throw(mixed $value): string
{
    $json = json_encode(
        $value,
        JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES
    );

    if ($json === false) {
        throw new RuntimeException('JSON encode failed: ' . json_last_error_msg());
    }

    return $json;
}

「ユーティリティの中で失敗を検知して、呼び出し側にちゃんと知らせる」 という設計にしておくと、バグの原因を追いやすくなります。

まとめ：今日からの「配列 → JSON（pretty）」ユーティリティ

このユーティリティの本質は、「構造を持ったデータを、人間が読める JSON 文字列にしてあげる」ことです。

そのために、

JSON_PRETTY_PRINT でインデントと改行を付ける。 JSON_UNESCAPED_UNICODE で日本語をそのまま出す。 JSON_UNESCAPED_SLASHES で URL などを見やすくする。

というフラグを組み合わせた json_encode を、 1 本の関数に閉じ込めておきます。

もう一度、基本形を載せておきます。

function to_pretty_json(mixed $value): string
{
    $json = json_encode(
        $value,
        JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES
    );

    if ($json === false) {
        return '';
    }

    return $json;
}

function to_pretty_json(mixed $value): string
{
    $json = json_encode(
        $value,
        JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES
    );

    if ($json === false) {
        return '';
    }

    return $json;
}

もし、あなたのコードのどこかで「json_encode($data) をそのままログや画面に出している」箇所があれば、 そこをこのユーティリティに差し替えてみてください。 JSON が「ただの文字列」から、「構造が一目で分かるデバッグの味方」に変わります。