json_encode/json_decode - returns stdClass instead of Array in PHP

json_encode/json_decode - returns stdClass instead of Array in PHP

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Why json_decode Returns stdClass Instead of Arrays in PHP

When you serialize a native PHP array using json_encode, the result is a standard JSON object string. However, decoding that string back into an object often yields a stdClass instance rather than restoring the original associative array. This behavior can catch developers off guard if they assume json_decode and json_encode are perfectly symmetric operations regarding data types.

The root cause lies in how PHP handles the distinction between JSON objects and JSON arrays versus its own internal representations. In PHP, an associative array is a specific construct where keys are strings and map to values. When json_encode processes this structure, it outputs valid JSON syntax: curly braces {} denote an object, and square brackets [] denote an array. The library has no way to distinguish between a JSON object and a native PHP associative array solely based on the string content; both look like objects in JSON.

Consequently, json_decode defaults to creating a stdClass object for any JSON object (curly braces). This default behavior preserves the structure of the data without forcing it back into a native PHP associative array, which might not be what you expect if your code relies on array functions like array_map, in_array, or foreach expecting strict array semantics.

To force json_decode to return an associative array instead of a stdClass object, you must pass the second argument as true. This tells PHP to reconstruct the structure as a native array whenever the JSON input is an object:

$jsonString = '{"stuff": "things"}';
$decodedArray = json_decode($jsonString, true);

print_r($decodedArray);
// Output: Array ( [stuff] => things )
var_dump(gettype($decodedArray));
// Output: string(6) "array"

By enabling the associative flag, you ensure that the decoded data behaves exactly like the original input in terms of type. This is crucial when your downstream logic depends on array-specific features or when you need to pass the data into functions that reject stdClass instances. Without this flag, attempting to use array functions on a stdClass will result in errors or warnings because stdClass objects do not support all dynamic property access patterns available to arrays without explicit casting.

There is a subtle trade-off to consider when deciding whether to decode with the associative flag enabled. While it restores the native array type, it also loses the ability to use object-oriented syntax on the properties. For example, if you were iterating over an API response expecting an object with public properties accessed via $item->name, decoding with true forces you to access properties as $item['name']. While functionally equivalent in most contexts, this shift can impact code readability and the use of modern PHP features like named arguments or destructuring.

In frameworks like Laravel, this distinction becomes even more relevant when handling API responses. The framework often automatically decodes JSON payloads, but understanding whether you are working with an array or a stdClass object helps prevent unexpected behavior in your controllers or models. If you rely on helper methods that assume arrays, failing to decode with the associative flag can lead to subtle bugs where data is accessible but treated as an object instead of a collection.

Ultimately, the choice between stdClass and native arrays depends on your specific requirements for type consistency versus object-oriented access patterns. If exact structural fidelity is required, explicitly decoding into an array is the safer approach. If you prefer accessing properties directly without bracket notation, the default stdClass behavior offers a convenient shorthand that aligns with JSON's object semantics.

Our network