🔧 json_encode()

シグネチャ

json_encode(mixed $value, int $flags = 0, int $depth = 512): string|false

引数 1

mixed $value

引数 2

int $flags = 0

引数 3

int $depth = 512

戻り値

string|false

解説

PHP の配列・オブジェクトを JSON 文字列に変換します。 API レスポンス生成、 ログ出力、 設定ファイルの永続化 などで頻出します。 日本語をエスケープせず出力するには `JSON_UNESCAPED_UNICODE`、 スラッシュを保つには `JSON_UNESCAPED_SLASHES`、 整形して読みやすくするには `JSON_PRETTY_PRINT` を指定します。

使用例

<?php
$data = ['name' => '太郎', 'age' => 30];
echo json_encode($data, JSON_UNESCAPED_UNICODE);
// {"name":"太郎","age":30}

// API で「失敗時に例外」 を強制
try {
    $json = json_encode($data, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
} catch (\JsonException $e) {
    // エンコード失敗時の処理
}

よくある用途

1. REST/JSON API のレスポンスボディ生成。 2. ログ出力で構造化データを 1 行に圧縮 (= JSON Lines 形式)。 3. JavaScript 側に PHP データを渡すための bootstrap data (= JSON_HEX_TAG 等で <script> 内に安全に埋め込み)。 4. 設定の永続化 (= JSON ファイルへの保存)。 5. メッセージキュー (Redis / Kafka) へのペイロード化。

落とし穴 / 注意点

❌ 失敗時は false が返るので必ずチェック (= もしくは `JSON_THROW_ON_ERROR` で例外化)。 ❌ float の精度: 0.1 + 0.2 = 0.30000000000000004 がそのまま JSON 化される (= JSON_PRESERVE_ZERO_FRACTION で 0 末尾保持)。 ❌ オブジェクトと連想配列の混在: PHP 配列でキーが数値だけだと JSON 配列、 文字列が混じると JSON オブジェクトになる。 厳密にどちらにしたいなら明示的に (object) キャストや (array) を使う。 ❌ 循環参照を含むオブジェクトはエンコード失敗します (= ResourceLoop)。 ❌ private プロパティはデフォルトでは出力されない (= JsonSerializable インタフェースを実装して制御)。

代替手段・関連関数

・symfony/serializer — DTO とのバインディング、 グループ別シリアライズ、 カスタム normalizer。 ・igbinary_serialize — バイナリ形式で速くて小さい (= 配信ではなく cache 用途)。 ・msgpack — JSON より小さく速い (= MessagePack)。 ・json_decode($str, true) — 配列で受け取りたい場合の対 (= true を渡す)。

公式マニュアル

https://www.php.net/manual/ja/function.json-encode.php