PHP JSON

JSON (JavaScript Object Notation) è un formato leggero e basato su testo per lo scambio di dati. È il modo più comune per inviare e ricevere dati tra un backend PHP e un browser, un'app mobile o un altro servizio web (la maggior parte delle API REST utilizza JSON). Questa guida copre tutto il necessario per lavorare con JSON in PHP: convertire i dati PHP in JSON con json_encode, riconvertire JSON in dati PHP con json_decode, formattare l'output e gestire gli errori in modo sicuro.

PHP include il supporto JSON nel suo core (l'estensione ext-json è inclusa e abilitata per impostazione predefinita da PHP 8.0), quindi non c'è nulla da installare.

Come appare JSON

JSON rappresenta i dati come coppie chiave-valore all'interno di oggetti ({ }) e liste ordinate all'interno di array ([ ]). I valori possono essere stringhe, numeri, booleani, null, array o oggetti annidati:

{
  "name": "John",
  "age": 30,
  "active": true,
  "roles": ["admin", "editor"]
}

Le due funzioni che userai quasi sempre sono:

• json_encode($value) — valore PHP → stringa JSON (serializzazione).
• json_decode($json) — stringa JSON → valore PHP (deserializzazione).

Codifica: da PHP a JSON con json_encode

json_encode() converte un valore PHP — tipicamente un array o un oggetto — in una stringa JSON.

Codifica di un array associativo

Un array associativo diventa un oggetto JSON, mentre un array indicizzato (chiavi intere sequenziali che partono da 0) diventa un array JSON:

<?php

echo json_encode(["red", "green", "blue"]);
// ["red","green","blue"]

?>

Formattare l'output

Per impostazione predefinita json_encode produce JSON compatto su una singola riga, ideale per l'invio in rete. Quando si desidera un output leggibile dall'uomo (per log o debug), è possibile passare il flag JSON_PRETTY_PRINT. I flag si combinano con l'operatore bit a bit |:

<?php

$data = [
    "user" => ["name" => "Jane", "roles" => ["admin", "editor"]],
    "active" => true,
];

echo json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);

?>

Questo stampa JSON con rientri ordinati:

{
    "user": {
        "name": "Jane",
        "roles": [
            "admin",
            "editor"
        ]
    },
    "active": true
}

Altri flag utili: JSON_UNESCAPED_SLASHES (mantiene / invece di \/) e JSON_UNESCAPED_UNICODE (mantiene caratteri come é invece di é).

Decodifica: da JSON a PHP con json_decode

json_decode() converte una stringa JSON in un valore PHP. Per impostazione predefinita restituisce oggetti, ma passando true come secondo argomento si ottengono invece array associativi — che di solito sono più semplici da iterare:

Senza l'argomento true, si ottiene un oggetto stdClass e si accede ai valori con la notazione freccia -> invece di [ ]:

Usa true quando vuoi un array; omettilo quando preferisci la sintassi degli oggetti. Entrambi contengono gli stessi dati.

Codifica di un oggetto personalizzato

json_encode funziona anche sugli oggetti. Quando è necessario costruire una struttura JSON al volo, l'oggetto stdClass vuoto consente di aggiungere proprietà dinamicamente. (Per le classi complete, consulta PHP Classes and Objects.)

Le proprietà pubbliche di qualsiasi oggetto vengono incluse automaticamente; le proprietà private e protette vengono ignorate a meno che la classe non implementi l'interfaccia JsonSerializable.

Gestione degli errori

Il parsing JSON può fallire — una stringa malformata, una virgoletta non terminata o una virgola finale possono compromettere la decodifica. Quando json_decode fallisce restituisce null, quindi occorre distinguere un valore null reale da un errore. Controlla json_last_error() (oppure leggi json_last_error_msg() per un messaggio leggibile dall'uomo):

<?php

$badJson = '{invalid}';
$result = json_decode($badJson);

if (json_last_error() !== JSON_ERROR_NONE) {
    echo "JSON error: " . json_last_error_msg();
    // JSON error: Syntax error
}

?>

Da PHP 7.3 è possibile passare il flag JSON_THROW_ON_ERROR per far sì che entrambe le funzioni lancino una JsonException, che si integra perfettamente nei blocchi try/catch:

<?php

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

?>

Nota: json_decode ha un limite di profondità (512 livelli per impostazione predefinita, il terzo argomento). JSON molto profondamente annidato fallirà con un errore JSON_ERROR_DEPTH a meno che non si aumenti tale limite.

Caso d'uso comune: lettura del corpo di una richiesta JSON

Quando un client invia JSON a un endpoint PHP (come fanno la maggior parte delle API), il corpo arriva come input grezzo anziché come $_POST. Leggilo con php://input e decodificalo:

<?php

$body = file_get_contents("php://input");
$data = json_decode($body, true);

// echo a JSON response back to the client
header("Content-Type: application/json");
echo json_encode(["received" => $data]);

?>

Conclusione

JSON è il formato standard per lo scambio di dati nelle applicazioni web moderne, e PHP lo rende semplice da utilizzare:

• Usa json_encode per convertire array e oggetti in JSON; aggiungi JSON_PRETTY_PRINT per un output leggibile.
• Usa json_decode per riconvertire JSON in PHP — passa true per ottenere un array, omettilo per un oggetto.
• Controlla sempre gli errori con json_last_error() o JSON_THROW_ON_ERROR prima di fidarti dei dati decodificati.

Con questi strumenti puoi inviare e ricevere JSON in modo affidabile tra il tuo codice PHP, database, browser e servizi web esterni.

Esercitazione