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

JSON_FORCE_OBJECT定数の使い方について、初心者にもわかりやすく解説します。

作成日: 2025年09月11日更新日: 2026年03月08日

基本的な使い方

JSON_FORCE_OBJECT定数は、PHPで配列をJSON形式に変換するjson_encode()関数に渡すことで、特定のエンコード挙動を指示するためのオプションを表す定数です。この定数を使用すると、PHPの空の配列（[]）が、通常であればJSONの空の配列（[]）としてエンコードされるところを、JSONの空のオブジェクト（{}）として強制的にエンコードするようになります。

PHPの配列は、文字列をキーとする連想配列の場合にはJSONのオブジェクトとして、数値のみをキーとする配列の場合にはJSONの配列としてエンコードされるのが一般的です。しかし、空の配列は常にJSONの空の配列として扱われます。外部のWeb APIなどと連携する際、たとえデータが空であっても、特定のフィールドには必ずJSONのオブジェクトが期待される場合があります。このようなケースで、PHPの空配列が意図せずJSONの空配列に変換されてしまい、APIの要求する形式と合致しない問題が発生することがあります。

JSON_FORCE_OBJECT定数をjson_encode()関数の引数として指定することで、PHPの空配列もJSONの空オブジェクトとして出力され、期待されるJSON構造を強制的に生成できます。これにより、APIの仕様に厳密に合わせた一貫性のあるJSONデータを提供できるようになり、データ連携時のエラーを防ぎ、システムの互換性を高める上で非常に役立ちます。

構文(syntax)


1<?php
2$data = ['item1', 'item2'];
3$json = json_encode($data, JSON_FORCE_OBJECT);
4echo $json;
5?>

引数(parameters)

引数なし

引数はありません

戻り値(return)

戻り値なし

戻り値はありません

サンプルコード

PHP: JSON_FORCE_OBJECT で配列をオブジェクト化する


1<?php
2
3/**
4 * PHPのJSON_FORCE_OBJECT定数の使用例を示します。
5 *
6 * この定数を使用すると、数値インデックス配列が強制的にJSONオブジェクトとしてエンコードされます。
7 * システムエンジニアを目指す初心者向けに、その挙動の違いを比較して解説します。
8 */
9function demonstrateJsonForceObject(): void
10{
11    // 数値インデックス配列を定義します。
12    // これは通常のPHPの配列で、キーが0, 1, 2... と自動的に割り振られます。
13    $numericIndexedArray = ['apple', 'banana', 'cherry'];
14
15    echo "--- 元のPHP配列 ---\n";
16    print_r($numericIndexedArray); // PHPの配列の内容を表示
17    echo "\n";
18
19    // 1. JSON_FORCE_OBJECT フラグを使用しない場合
20    // 通常の数値インデックス配列は、JSON配列 ([...]) としてエンコードされます。
21    echo "--- JSON_FORCE_OBJECT なしでのエンコード ---\n";
22    $jsonDefault = json_encode($numericIndexedArray);
23    echo "結果 (JSON配列): " . $jsonDefault . "\n\n";
24    // 出力例: ["apple","banana","cherry"]
25
26    // 2. JSON_FORCE_OBJECT フラグを使用する場合
27    // このフラグを json_encode() の第2引数に渡すことで、
28    // 数値インデックス配列が強制的にJSONオブジェクト ({...}) としてエンコードされます。
29    // 配列の数値キーが、JSONオブジェクトの文字列キー ('0', '1'...) に変換されます。
30    echo "--- JSON_FORCE_OBJECT ありでのエンコード ---\n";
31    $jsonForcedObject = json_encode($numericIndexedArray, JSON_FORCE_OBJECT);
32    echo "結果 (JSONオブジェクト): " . $jsonForcedObject . "\n\n";
33    // 出力例: {"0":"apple","1":"banana","2":"cherry"}
34}
35
36// 上記の関数を実行して、JSON_FORCE_OBJECT の動作を確認します。
37demonstrateJsonForceObject();

PHPのJSON_FORCE_OBJECT定数は、配列をJSON形式に変換する際に、数値インデックスの配列のエンコード方法を制御するために使用されます。通常、json_encode()関数に['apple', 'banana']のような数値インデックス配列を渡すと、JSONの配列形式である["apple", "banana"]としてエンコードされます。

しかし、json_encode()関数の第二引数にJSON_FORCE_OBJECT定数を指定すると、この挙動が変わります。数値インデックス配列であっても、強制的にJSONオブジェクト形式でエンコードされるようになるのです。この際、元の配列の数値キー（例: 0, 1）が、JSONオブジェクトの文字列キー（例: "0", "1"）として扱われ、{"0":"apple", "1":"banana"}のように変換されます。

この定数自体には引数や戻り値はありませんが、json_encode関数に渡すことで、その関数の出力形式に影響を与えます。この機能は、API連携などで常にJSONオブジェクト形式でのデータ送受信が求められる場合に特に便利です。

PHPのJSON_FORCE_OBJECT定数は、json_encode使用時の重要な注意点です。通常、数値インデックス配列はJSON配列としてエンコードされますが、この定数を指定すると、配列が強制的にJSONオブジェクトへと変換されます。この際、数値キーも文字列キーに変わるため、["apple"]が{"0":"apple"}となる挙動を理解しておく必要があります。この機能は、外部APIとの連携で特定のJSONオブジェクト形式が必須となる場合に役立ちますが、意図せず使用すると、JSONを受信するシステムでパースエラーや予期せぬ問題を引き起こす可能性があります。常に、JSONの受け取り側がどのような形式を期待しているかを確認し、必要に応じて利用するよう心がけてください。