Capire la funzione json_decode in PHP

La funzione json_decode in PHP trasforma una stringa in formato JSON in un valore PHP nativo che puoi leggere e manipolare. È la controparte di json_encode, che fa il contrario (valore PHP → stringa JSON). Si ricorre a json_decode ogni volta che i dati arrivano come testo e occorre elaborarli: una risposta di un'API REST, un payload di un webhook, un file di configurazione o una colonna memorizzata in un database.

Questo capitolo tratta la firma della funzione, la differenza tra la decodifica in oggetto e in array associativo, il comportamento dei dati annidati, le opzioni di profondità e flag, e il modo corretto di gestire l'input non valido.

Cos'è JSON?

JSON (JavaScript Object Notation) è un formato di scambio dati leggero e testuale, facile da leggere per gli esseri umani e da analizzare per le macchine. Rappresenta i dati come coppie chiave-valore (oggetti, scritti {}) e liste ordinate (array, scritti []), con stringhe, numeri, booleani e null come valori scalari. Poiché quasi ogni linguaggio è in grado di produrlo e consumarlo, JSON è diventato il formato predefinito per le API web. Consulta la panoramica su PHP e JSON per il quadro generale.

Sintassi

json_decode(string $json, ?bool $associative = null, int $depth = 512, int $flags = 0): mixed

Parametro	Scopo
`$json`	La stringa JSON da decodificare. Deve essere UTF-8 valido.
`$associative`	`true` → restituisce array associativi; `false`/`null` → restituisce oggetti `stdClass`.
`$depth`	Profondità di annidamento massima consentita (predefinito `512`). La decodifica di input più profondi ha esito negativo.
`$flags`	Bitmask di opzioni, ad es. `JSON_THROW_ON_ERROR`, `JSON_BIGINT_AS_STRING`.

La funzione restituisce il valore decodificato (array, stdClass, string, int, float, bool o null), oppure null in caso di errore.

Decodifica di una stringa JSON

L'utilizzo più comune è la decodifica di un oggetto JSON. Passa true come secondo argomento per ottenere un array associativo PHP.

Esempio della funzione PHP json_decode

php— editable, runs on the server

Qui $json rappresenta il nome, l'età e la città di una persona. Con true, json_decode costruisce un array PHP, quindi il risultato è:

Array
(
    [name] => John
    [age] => 30
    [city] => New York
)

Puoi quindi leggere i valori con la sintassi degli array, ad es. $array['name']. Consulta gli array associativi per ulteriori dettagli su questa struttura dati.

Utilizzo del secondo parametro

Il secondo parametro della funzione json_decode è facoltativo, ma viene spesso usato per controllare il tipo della variabile restituita. Se impostato su true, json_decode restituirà un array. Se impostato su false (valore predefinito), json_decode restituirà un oggetto.

Esempio della funzione PHP json_decode con oggetti

php— editable, runs on the server

Quando $associative è false (o omesso), json_decode restituisce un oggetto stdClass. Puoi leggere i valori con la sintassi delle proprietà dell'oggetto $object->name, $object->age e così via. Usa questa forma quando preferisci l'accesso in stile oggetto o quando il risultato verrà passato a codice che si aspetta oggetti (vedi classi e oggetti PHP).

Decodifica di JSON annidato

I dati JSON nel mondo reale sono solitamente annidati. json_decode gestisce l'annidamento automaticamente: ogni livello diventa un array annidato (con true) o un oggetto annidato (con false).

<?php

$json = '{"user":{"name":"John","roles":["admin","editor"]}}';
$data = json_decode($json, true);

echo $data['user']['name'];      // John
echo "\n";
echo $data['user']['roles'][0];  // admin

?>

Gli oggetti JSON interni diventano array interni, e gli array JSON ([...]) diventano array PHP indicizzati su cui è possibile iterare con foreach.

Gestione degli errori

Se la stringa passata a json_decode non è un JSON valido, la funzione restituisce null. Tuttavia, null è anche un valore JSON valido, quindi controllare if ($array === null) non consente di distinguere tra un errore di decodifica e una decodifica riuscita del valore letterale null. Per gestire correttamente gli errori, controlla json_last_error() oppure usa il flag JSON_THROW_ON_ERROR (PHP 7.3+).

Gestione degli errori di json_decode in PHP

php— editable, runs on the server

Alla stringa sopra manca una virgoletta di chiusura, quindi json_last_error() non è JSON_ERROR_NONE e il messaggio spiega cosa è andato storto.

Da PHP 7.3 in poi, l'opzione più pulita è il flag JSON_THROW_ON_ERROR, che genera una JsonException invece di restituire silenziosamente null:

<?php

try {
    $data = json_decode('{"invalid": }', true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    echo "Could not decode JSON: " . $e->getMessage();
}

?>

Ciò consente di gestire l'input non valido con i normali blocchi try/catch invece di controllare manualmente il risultato dopo ogni chiamata.

Funzioni correlate

json_encode — converte un valore PHP in una stringa JSON.
PHP e JSON — panoramica sull'utilizzo di JSON in PHP.
Riferimento PHP JSON — elenco completo delle funzioni e costanti JSON di PHP.

Conclusione

La funzione json_decode in PHP è uno strumento potente per lavorare con i dati JSON. È veloce, affidabile e semplice da usare. Comprendendo i dettagli di json_decode e del suo secondo parametro, puoi decodificare stringhe JSON con sicurezza e utilizzare i dati risultanti nelle tue applicazioni PHP.

Esercitazione

Pratica

Cosa fa la funzione json_decode() in PHP?

Converte una stringa JSON in una variabile PHP.Decodifica dati codificati in base64.Converte i caratteri HTML nelle loro entità.Permette di passare true come secondo argomento per convertire gli oggetti JSON in array associativi.