PHP json_decode(): convertire JSON in array o oggetti

json_decode($json, true) trasforma una stringa JSON in valori PHP, con ogni oggetto JSON come array associativo. Ometti true e gli oggetti JSON diventano invece oggetti stdClass, letti con ->. Un JSON non valido dà 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);

Output:

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

    [admin] => 1
)

Gli array JSON diventano sempre liste PHP, qualunque modalità tu scelga. Per la direzione opposta, da PHP a JSON, c'è json_encode().

Array associativo o oggetto: true vs false

Entrambe le modalità contengono gli stessi dati; scegli quella che si legge meglio nel tuo codice. Gli array funzionano con ogni funzione per array (array_column, array_map, isset($data['key'])), quindi la maggior parte del codice passa true. Gli oggetti richiedono la sintassi con le graffe per le chiavi che non sono nomi di proprietà validi, come chiavi con un trattino o un numero:

<?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);

Output:

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

Il quarto parametro accetta dei flag. Anche JSON_OBJECT_AS_ARRAY dà array, ma solo finché il secondo argomento è null (il suo default): json_decode($json, flags: JSON_OBJECT_AS_ARRAY) restituisce array, mentre json_decode($json, false, 512, JSON_OBJECT_AS_ARRAY) restituisce ancora oggetti.

Scorrere un JSON annidato

Le risposte delle API sono di solito una lista di oggetti dentro un oggetto. Decodifica una volta, poi percorrila con foreach, e usa ?? per i campi che potrebbero mancare:

<?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);

Output:

#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
)

Gestire un JSON non valido

json_decode() restituisce null per un JSON non valido, ma null è anche il risultato corretto per il testo JSON null, quindi null da solo non ti dice se è fallito. json_last_error_msg() dà il motivo dell'ultima chiamata. Il modo più pulito è JSON_THROW_ON_ERROR, che lancia 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";
}

Output:

NULL
Syntax error
NULL
No error
Invalid JSON: Syntax error

Il terzo argomento, 512, è la profondità massima di annidamento (il default). Con gli argomenti con nome puoi saltarlo: json_decode($json, true, flags: JSON_THROW_ON_ERROR).

Verificare se una stringa è un JSON valido con json_validate()

PHP 8.3 ha aggiunto json_validate(). Risponde true o false senza costruire gli array decodificati, quindi usa meno memoria della decodifica quando ti serve solo un sì o un no, per esempio per rifiutare subito il corpo di una richiesta:

<?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";
}

Output:

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

Se userai comunque i dati, salta json_validate() e decodifica con JSON_THROW_ON_ERROR: validare prima analizza la stringa due volte.

Leggere un file JSON

Leggi il file con file_get_contents() e decodifica la stringa. Questo blocco scrive prima settings.json così c'è un file da leggere:

<?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";

Output:

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

Perché json_decode restituisce null: le cause abituali

Il JSON è più rigoroso della sintassi degli array di JavaScript e PHP. Ogni stringa qui sotto sembra ragionevole e ognuna restituisce null. Eseguilo per vedere il motivo di ciascuna, poi correggine una ed eseguilo di nuovo:

<?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']);

Output:

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"

Un byte order mark è invisibile nella maggior parte degli editor ed è il motivo classico per cui un file JSON "sembra a posto" ma non si decodifica. Toglilo con $text = preg_replace('/^\xEF\xBB\xBF/', '', $text); prima di decodificare.