Codifica JSON con PHP

JSON (JavaScript Object Notation) è un formato leggero di scambio dati basato su testo, facile da leggere per gli esseri umani e semplice da analizzare per le macchine. È il formato de facto per inviare dati tra un server e il browser, per le API REST e per i file di configurazione. In PHP, json_encode() prende un valore PHP — uno scalare, un array o un oggetto — e restituisce la sua rappresentazione JSON come stringa.

Questa pagina tratta la sintassi, i $flags più utili, come i tipi PHP vengono mappati in JSON e come rilevare gli errori di codifica. Per l'operazione inversa (stringa JSON → valore PHP) vedere json_decode().

Sintassi

json_encode(mixed $value, int $flags = 0, int $depth = 512): string|false

Restituisce una stringa codificata in JSON in caso di successo, oppure false in caso di errore (ad esempio, quando l'input contiene byte UTF-8 non validi).

Parametri

• $value — il valore da codificare. Può essere di qualsiasi tipo eccetto un resource. Tutti i dati stringa devono essere UTF-8 validi.
• $flags (opzionale) — una maschera di bit che personalizza l'output. I più comuni:
  • JSON_PRETTY_PRINT — aggiunge spazi bianchi e indentazione per rendere l'output leggibile.
  • JSON_UNESCAPED_UNICODE — mantiene i caratteri multibyte (é, ñ, 日) letterali invece di convertirli in \uXXXX.
  • JSON_UNESCAPED_SLASHES — lascia / senza escape (PHP lo converte in \/ per impostazione predefinita).
  • JSON_FORCE_OBJECT — codifica un array sequenziale come oggetto JSON ({}) invece di un array ([]).
  • JSON_THROW_ON_ERROR — lancia una JsonException in caso di errore invece di restituire false (PHP 7.3+).
  • Combina i flag con l'operatore OR bit a bit: JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE.
• $depth (opzionale) — la profondità massima di annidamento. Deve essere maggiore di 0. Il valore predefinito di 512 è sufficiente per dati normali.

Come i tipi PHP vengono mappati in JSON

Esempi

Codifica di un array

Un array associativo PHP diventa un oggetto JSON; le chiavi diventano nomi di proprietà.

Output:

{"a":1,"b":2,"c":3,"d":4,"e":5}

Codifica di un oggetto

Le proprietà pubbliche di un oggetto vengono codificate; le proprietà private e protected vengono ignorate.

Output:

{"name":"John Doe","age":35,"city":"New York"}

Pretty-print e Unicode non escapato

Per impostazione predefinita l'output è compatto, su una riga, e i caratteri non ASCII vengono escapati (ad esempio é diventa é). Due flag rendono l'output leggibile dall'utente:

<?php

$data = [
    "name"  => "Café",
    "tags"  => ["php", "json"],
    "price" => 9.50,
];

echo json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);

?>

Output:

{
    "name": "Café",
    "tags": [
        "php",
        "json"
    ],
    "price": 9.5
}

Nota che 9.50 viene emesso come 9.5 — gli zeri finali dei numeri in virgola mobile vengono eliminati. Usa JSON_PRESERVE_ZERO_FRACTION se hai bisogno che 9.0 rimanga un float invece di diventare 9.

Gestione degli errori

Se json_encode() restituisce false, qualcosa è andato storto — nella maggior parte dei casi si tratta di byte UTF-8 non validi in una stringa. Controlla json_last_error_msg(), oppure passa JSON_THROW_ON_ERROR per ottenere un'eccezione al posto.

<?php

$value = json_encode("\xB1\x31"); // invalid UTF-8 byte sequence

if ($value === false) {
    echo "Encoding failed: " . json_last_error_msg();
}

?>

Output:

Encoding failed: Malformed UTF-8 characters, possibly incorrectly encoded

Casi d'uso comuni

• Restituire dati da un'API. Imposta l'header ed esegui l'echo dell'array codificato:

  header('Content-Type: application/json');
  echo json_encode(['status' => 'ok', 'items' => $items]);

  Copia

• Memorizzare dati strutturati in un file o in una colonna di testo di un database invece di serialize(). JSON è portabile tra linguaggi diversi; serialize() è specifico per PHP.

• Passare dati a JavaScript renderizzato nella pagina, poiché il JSON valido è anche sintassi di oggetto JavaScript valida.

Conclusione

json_encode() converte array e oggetti PHP in una stringa JSON compatta e portabile. Usa JSON_PRETTY_PRINT e JSON_UNESCAPED_UNICODE quando l'output deve essere letto da un essere umano, proteggi l'applicazione da input non validi controllando il valore restituito o usando JSON_THROW_ON_ERROR, e ricorda che vengono codificate solo le proprietà pubbliche degli oggetti. Per analizzare JSON e ottenere un valore PHP, usa json_decode(); per una panoramica più ampia, vedi Lavorare con JSON in PHP.

Esercitazione