Riferimento alle funzioni JSON di PHP

JSON (JavaScript Object Notation) è un formato di scambio dati leggero e basato su testo. Poiché è facile da leggere per gli esseri umani e semplice da analizzare per le macchine, è diventato il metodo predefinito per inviare dati tra un server e un browser, e tra i servizi web (REST API).

PHP include un piccolo insieme di funzioni integrate — collettivamente chiamate estensione JSON — che convertono i valori PHP in testo JSON e viceversa. Questa pagina è un riferimento rapido a quelle funzioni e alle costanti di opzione più utili. Per un tutorial passo passo, consulta PHP JSON.

Quando usare JSON in PHP?

Si ricorre a queste funzioni ogni volta che i dati devono uscire da PHP come testo o arrivare come testo:

• Restituire dati da un endpoint API (echo json_encode($data);).
• Leggere il corpo di una richiesta o un file di configurazione scritto in JSON.
• Memorizzare un valore strutturato (ad esempio un array di impostazioni) in una singola colonna del database o chiave di cache.
• Comunicare con un servizio web di terze parti che utilizza JSON.

L'estensione JSON è abilitata per impostazione predefinita in PHP 5.2 e versioni successive, ed è parte del core in PHP 8.0+, quindi non è necessaria alcuna installazione.

Funzioni JSON

json_encode()

json_encode() serializza un valore PHP in una stringa formattata come JSON.

<?php

$data = [
    "name"  => "Ada",
    "age"   => 36,
    "langs" => ["PHP", "JS"],
];

echo json_encode($data);

?>

Output:

{"name":"Ada","age":36,"langs":["PHP","JS"]}

Nota come un array associativo diventa un oggetto JSON {}, mentre un array di tipo lista (["PHP","JS"]) diventa un array JSON []. Consulta il riferimento completo in json_encode().

Formattazione leggibile dell'output

Passa l'opzione JSON_PRETTY_PRINT per rendere il risultato leggibile:

<?php

$data = ["name" => "Ada", "langs" => ["PHP", "JS"]];

echo json_encode($data, JSON_PRETTY_PRINT);

?>

Output:

{
    "name": "Ada",
    "langs": [
        "PHP",
        "JS"
    ]
}

json_decode()

json_decode() analizza una stringa JSON e la trasforma in un valore PHP. Per impostazione predefinita restituisce oggetti (stdClass); passa true come secondo argomento per ottenere array associativi.

<?php

$json = '{"name":"Ada","age":36,"langs":["PHP","JS"]}';

// Decode as an associative array
$data = json_decode($json, true);

echo $data["name"];   // Ada
echo "\n";
echo $data["langs"][0]; // PHP

?>

Output:

Ada
PHP

Consulta il riferimento completo in json_decode().

Gestione degli errori

json_encode() restituisce false e json_decode() restituisce null quando qualcosa va storto (UTF-8 non valido, un errore di sintassi nell'input, o una nidificazione più profonda del limite). Poiché null è anche un valore valido decodificato, controlla sempre json_last_error() anziché verificare solo la presenza di null.

<?php

$bad = '{"name": "Ada", }';   // trailing comma is invalid JSON

$result = json_decode($bad, true);

if (json_last_error() !== JSON_ERROR_NONE) {
    echo "Invalid JSON: " . json_last_error_msg();
} else {
    echo "Decoded fine.";
}

?>

Output:

Invalid JSON: Syntax error

In PHP 7.3+ puoi passare il flag JSON_THROW_ON_ERROR a entrambe le funzioni per ottenere una JsonException invece di ispezionare manualmente il codice di errore.

Costanti di opzione comuni

Queste costanti bitmask vengono passate nell'argomento $options di json_encode() (e alcune si applicano anche a json_decode()):

• JSON_PRETTY_PRINT — formatta l'output con spazi bianchi e indentazione.
• JSON_UNESCAPED_SLASHES — lascia i caratteri / non escapati (http:// invece di http:\/\/).
• JSON_UNESCAPED_UNICODE — mantiene i caratteri multibyte così come sono invece delle sequenze di escape \uXXXX.
• JSON_THROW_ON_ERROR — lancia una JsonException in caso di errore (PHP 7.3+).
• JSON_FORCE_OBJECT — emette sempre un oggetto JSON, anche per un array sequenziale.

Combinali con l'operatore OR bit a bit:

<?php

$data = ["site" => "https://www.w3docs.com", "name" => "café"];

echo json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);

?>

Output:

{
    "site": "https://www.w3docs.com",
    "name": "café"
}

Argomenti correlati

• PHP JSON — la guida completa introduttiva.
• PHP Arrays e Array Associativi — le strutture che si mappano più naturalmente a JSON.
• Funzioni PHP — come racchiudere encode/decode nei propri helper.

Esercitazione