PHP json_decode(): convertir JSON en arrays u objetos

json_decode($json, true) convierte una cadena JSON en valores de PHP, con cada objeto JSON como un array asociativo. Si omites true, los objetos JSON se convierten en objetos stdClass, que se leen con ->. Un JSON no válido da null.

<?php
$json = '{"name": "Ada", "age": 36, "langs": ["php", "js"], "admin": true}';

$data = json_decode($json, true);   // associative array
echo $data['name'], "\n";
echo $data['langs'][1], "\n";

$obj = json_decode($json);          // stdClass object
echo $obj->name, "\n";
echo $obj->langs[0], "\n";

print_r($data);

Salida:

Ada
js
Ada
php
Array
(
    [name] => Ada
    [age] => 36
    [langs] => Array
        (
            [0] => php
            [1] => js
        )

    [admin] => 1
)

Los arrays JSON siempre se convierten en listas de PHP, elijas el modo que elijas. La dirección contraria, de PHP a JSON, es json_encode().

Array asociativo u objeto: true vs false

Los dos modos contienen los mismos datos; elige el que se lea mejor en tu código. Los arrays funcionan con todas las funciones de arrays (array_column, array_map, isset($data['key'])), así que la mayoría del código pasa true. Los objetos necesitan la sintaxis con llaves para las claves que no son nombres de propiedad válidos, como las claves con un guion o un número:

<?php
$json = '{"first-name": "Ada", "0": "zero", "address": {"city": "London"}}';

$arr = json_decode($json, true);
echo $arr['first-name'], ' ', $arr[0], ' ', $arr['address']['city'], "\n";

$obj = json_decode($json);
echo $obj->{'first-name'}, ' ', $obj->{'0'}, ' ', $obj->address->city, "\n";

var_dump($obj->address);

Salida:

Ada zero London
Ada zero London
object(stdClass)#2 (1) {
  ["city"]=>
  string(6) "London"
}

El cuarto parámetro recibe opciones. JSON_OBJECT_AS_ARRAY también da arrays, pero solo mientras el segundo argumento sea null (su valor por defecto): json_decode($json, flags: JSON_OBJECT_AS_ARRAY) devuelve arrays, mientras que json_decode($json, false, 512, JSON_OBJECT_AS_ARRAY) sigue devolviendo objetos.

Recorrer JSON anidado

Las respuestas de las APIs suelen ser una lista de objetos dentro de un objeto. Decodifica una vez, recórrelo con foreach y usa ?? para los campos que pueden faltar:

<?php
$json = <<<'JSON'
{
    "page": 1,
    "users": [
        {"id": 1, "name": "Ada", "email": "ada@example.com", "roles": ["admin", "editor"]},
        {"id": 2, "name": "Linus", "roles": []},
        {"id": 3, "name": "Grace", "email": "grace@example.com", "roles": ["editor"]}
    ]
}
JSON;

$data = json_decode($json, true);

foreach ($data['users'] as $user) {
    $email = $user['email'] ?? 'no email';
    $roles = $user['roles'] ? implode(', ', $user['roles']) : 'none';
    echo "#{$user['id']} {$user['name']} <$email> roles: $roles\n";
}

$names = array_column($data['users'], 'name', 'id');
print_r($names);

Salida:

#1 Ada <ada@example.com> roles: admin, editor
#2 Linus <no email> roles: none
#3 Grace <grace@example.com> roles: editor
Array
(
    [1] => Ada
    [2] => Linus
    [3] => Grace
)

Manejar JSON no válido

json_decode() devuelve null con un JSON no válido, pero null es también el resultado correcto para el texto JSON null, así que null por sí solo no te dice si falló. json_last_error_msg() da el motivo de la última llamada. La forma más limpia es JSON_THROW_ON_ERROR, que lanza una JsonException:

<?php
var_dump(json_decode('{"a": 1,}'));   // trailing comma
echo json_last_error_msg(), "\n";

var_dump(json_decode('null'));        // valid JSON, also null
echo json_last_error_msg(), "\n";

try {
    $data = json_decode("{'a': 1}", true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    echo 'Invalid JSON: ', $e->getMessage(), "\n";
}

Salida:

NULL
Syntax error
NULL
No error
Invalid JSON: Syntax error

El tercer argumento, 512, es la profundidad máxima de anidamiento (el valor por defecto). Con argumentos con nombre puedes saltártelo: json_decode($json, true, flags: JSON_THROW_ON_ERROR).

Comprobar si una cadena es JSON válido con json_validate()

PHP 8.3 añadió json_validate(). Responde true o false sin construir los arrays decodificados, así que usa menos memoria que decodificar cuando solo necesitas un sí o un no, por ejemplo para rechazar pronto el cuerpo de una petición:

<?php
$inputs = ['{"a": 1}', '[1, 2, 3]', '"text"', '{a: 1}', "{'a': 1}", ''];

foreach ($inputs as $input) {
    $ok = json_validate($input) ? 'valid' : 'invalid: ' . json_last_error_msg();
    echo str_pad(var_export($input, true), 14), $ok, "\n";
}

Salida:

'{"a": 1}'    valid
'[1, 2, 3]'   valid
'"text"'      valid
'{a: 1}'      invalid: Syntax error
'{\'a\': 1}'  invalid: Syntax error
''            invalid: Syntax error

Si vas a usar los datos de todas formas, sáltate json_validate() y decodifica con JSON_THROW_ON_ERROR: validar primero analiza la cadena dos veces.

Leer un archivo JSON

Lee el archivo con file_get_contents() y decodifica la cadena. Este bloque escribe primero settings.json para que haya un archivo que leer:

<?php
file_put_contents('settings.json', '{"theme": "dark", "fontSize": 14, "plugins": ["git", "lint"]}');

$text = file_get_contents('settings.json');
if ($text === false) {
    exit("Cannot read settings.json\n");
}

$settings = json_decode($text, true, flags: JSON_THROW_ON_ERROR);
echo "Theme: {$settings['theme']}\n";
echo "Plugins: ", count($settings['plugins']), "\n";

// Change a value and write the file back
$settings['fontSize'] = 16;
file_put_contents('settings.json', json_encode($settings, JSON_PRETTY_PRINT));
echo file_get_contents('settings.json'), "\n";

Salida:

Theme: dark
Plugins: 2
{
    "theme": "dark",
    "fontSize": 16,
    "plugins": [
        "git",
        "lint"
    ]
}

Por qué json_decode devuelve null: las causas habituales

JSON es más estricto que JavaScript y que la sintaxis de arrays de PHP. Todas las cadenas de abajo parecen razonables y todas devuelven null. Ejecútalo para ver el motivo de cada una, luego corrige una y vuelve a ejecutarlo:

<?php
$cases = [
    'single quotes'   => "{'name': 'Ada'}",
    'unquoted key'    => '{name: "Ada"}',
    'trailing comma'  => '{"name": "Ada",}',
    'comment'         => '{"name": "Ada" /* admin */}',
    'byte order mark' => "\xEF\xBB\xBF" . '{"name": "Ada"}',
    'too deep'        => '[[["Ada"]]]',
];

foreach ($cases as $label => $json) {
    $depth = $label === 'too deep' ? 2 : 512;
    $result = json_decode($json, true, $depth);
    echo str_pad($label, 17), $result === null ? json_last_error_msg() : 'ok', "\n";
}

// Big integers lose precision unless you ask for strings
var_dump(json_decode('{"id": 12345678901234567890}', true)['id']);
var_dump(json_decode('{"id": 12345678901234567890}', true, 512, JSON_BIGINT_AS_STRING)['id']);

Salida:

single quotes    Syntax error
unquoted key     Syntax error
trailing comma   Syntax error
comment          Syntax error
byte order mark  Syntax error
too deep         Maximum stack depth exceeded
float(1.2345678901234567E+19)
string(20) "12345678901234567890"

Una marca de orden de bytes es invisible en la mayoría de los editores y es el motivo clásico de que un archivo JSON "se vea bien" pero no se decodifique. Quítala con $text = preg_replace('/^\xEF\xBB\xBF/', '', $text); antes de decodificar.