PHP json_encode(): convertire array e oggetti in JSON

Q: Come converto un array PHP in JSON?

Passalo a jsonencode(): jsonencode(['name' => 'Ada', 'age' => 36]) restituisce {"name":"Ada","age":36}. Un array con chiavi 0, 1, 2... in ordine diventa invece un array JSON: json_encode(['a', 'b']) restituisce ["a","b"].

Q: Come stampo un JSON formattato in PHP?

Aggiungi il flag JSONPRETTYPRINT: jsonencode($data, JSONPRETTYPRINT) indenta con 4 spazi e mette ogni valore su una riga a sé. Combina i flag con |, per esempio JSONPRETTYPRINT | JSONUNESCAPED_UNICODE.

Q: Come faccio a ottenere {} invece di [] da json_encode per un array vuoto?

Un array PHP vuoto viene sempre codificato come []. Usa new stdClass() o (object) [] per un oggetto vuoto, oppure il flag JSONFORCEOBJECT, che trasforma in oggetto ogni array contenuto nel valore.

json_encode($value) restituisce il testo JSON di un valore PHP. Un array associativo diventa un oggetto JSON, una lista (chiavi 0, 1, 2...) diventa un array JSON, e stringhe, numeri, true, false e null diventano i loro equivalenti JSON.

<?php
$user = [
    'name'    => 'Ada',
    'age'     => 36,
    'langs'   => ['php', 'js'],
    'admin'   => true,
    'manager' => null,
];

$json = json_encode($user);
echo $json, "\n";
echo gettype($json), "\n";

Output:

{"name":"Ada","age":36,"langs":["php","js"],"admin":true,"manager":null}
string

Il risultato è una semplice stringa, pronta da inviare a un browser, salvare in un file o in una colonna di database, o passare a un altro programma. Per riconvertire un JSON in PHP, usa json_decode().

JSON formattato

json_encode() accetta dei flag come secondo argomento. JSON_PRETTY_PRINT aggiunge a capo e un'indentazione di 4 spazi, ciò che vuoi in un file di configurazione o in un log di debug. Combina più flag con |:

<?php
$config = [
    'app'   => 'shop',
    'debug' => false,
    'db'    => ['host' => 'localhost', 'port' => 3306],
    'tags'  => [],
];

echo json_encode($config, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES), "\n";

Output:

{
    "app": "shop",
    "debug": false,
    "db": {
        "host": "localhost",
        "port": 3306
    },
    "tags": []
}

Mantenere leggibile il giapponese e altro testo UTF-8

Di default json_encode() scrive ogni carattere non ASCII come escape \u e mette una barra rovesciata prima di ogni /. Entrambi sono JSON valido e si decodificano nello stesso testo, ma rendono l'output difficile da leggere e più lungo. JSON_UNESCAPED_UNICODE mantiene i caratteri, e JSON_UNESCAPED_SLASHES lascia gli URL come sono:

<?php
$item = ['name' => 'りんご', 'price' => 120, 'url' => 'https://example.com/fruit/apple'];

echo json_encode($item), "\n";
echo json_encode($item, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), "\n";

Output:

{"name":"\u308a\u3093\u3054","price":120,"url":"https:\/\/example.com\/fruit\/apple"}
{"name":"りんご","price":120,"url":"https://example.com/fruit/apple"}

Se il testo giapponese appare corrotto dopo la decodifica, il problema non sono gli escape: la stringa non era UTF-8 fin dall'inizio. json_encode() accetta solo UTF-8 e restituisce false per qualsiasi altra cosa, come mostra la sezione sugli errori.

Quando un array diventa un oggetto invece di una lista

Un array PHP viene codificato come array JSON solo quando le sue chiavi sono esattamente 0, 1, 2... in ordine. Qualsiasi altra chiave lo rende un oggetto JSON. Questo sorprende dopo unset() o array_filter(), che lasciano buchi nelle chiavi:

<?php
$fruits = ['apple', 'banana', 'cherry'];
unset($fruits[1]);

echo json_encode($fruits), "\n";                // keys 0, 2: an object
echo json_encode(array_values($fruits)), "\n";  // renumbered: a list

echo json_encode([1 => 'a', 2 => 'b']), "\n";   // does not start at 0

echo json_encode([]), "\n";                     // empty array: always []
echo json_encode(new stdClass()), "\n";         // empty object
echo json_encode(['a', 'b'], JSON_FORCE_OBJECT), "\n";

Output:

{"0":"apple","2":"cherry"}
["apple","cherry"]
{"1":"a","2":"b"}
[]
{}
{"0":"a","1":"b"}

Chiama array_values() prima della codifica ogni volta che il codice che riceve si aspetta una lista. Se si aspetta un oggetto che potrebbe essere vuoto, usa new stdClass() o (object) $array così anche un valore vuoto esce come {}.

Codificare un oggetto e controllarne il JSON con JsonSerializable

Un oggetto semplice viene codificato solo con le sue proprietà public; quelle protected e private vengono saltate. Per decidere esattamente come appare un oggetto in JSON, implementa l'interfaccia JsonSerializable e restituisci i dati da jsonSerialize():

<?php
class User
{
    public string $name = 'Ada';
    public ?string $nick = null;
    private string $password = 'secret';   // never encoded
}

echo json_encode(new User()), "\n";

// A date object encodes its internals, which is rarely what an API wants
echo json_encode(new DateTimeImmutable('2026-03-14 09:30')), "\n";

class Order implements JsonSerializable
{
    public function __construct(
        private int $id,
        private float $total,
        private DateTimeImmutable $created,
    ) {}

    public function jsonSerialize(): array
    {
        return [
            'id'      => $this->id,
            'total'   => $this->total,
            'created' => $this->created->format(DATE_ATOM),
        ];
    }
}

$order = new Order(7, 19.5, new DateTimeImmutable('2026-03-14 09:30'));
echo json_encode($order, JSON_PRETTY_PRINT), "\n";

Output:

{"name":"Ada","nick":null}
{"date":"2026-03-14 09:30:00.000000","timezone_type":3,"timezone":"UTC"}
{
    "id": 7,
    "total": 19.5,
    "created": "2026-03-14T09:30:00+00:00"
}

Un backed enum come enum Status: string viene codificato come il suo valore ("active"). Un enum puro non ha valore, quindi json_encode() fallisce con "Non-backed enums have no default serialization".

Numeri, float e stringhe numeriche

Interi e float vengono scritti come numeri JSON, e le stringhe restano stringhe anche quando contengono cifre. Tre flag cambiano questo comportamento:

<?php
echo json_encode(['price' => 10.0]), "\n";                               // 10.0 loses its .0
echo json_encode(['price' => 10.0], JSON_PRESERVE_ZERO_FRACTION), "\n";
echo json_encode(0.1 + 0.2), "\n";                                       // full float precision

echo json_encode(['qty' => '3', 'id' => '007']), "\n";
echo json_encode(['qty' => '3', 'id' => '007'], JSON_NUMERIC_CHECK), "\n";

Output:

{"price":10}
{"price":10.0}
0.30000000000000004
{"qty":"3","id":"007"}
{"qty":3,"id":7}

JSON_NUMERIC_CHECK converte ogni stringa numerica, quindi un ID come "007" o un codice postale come "01234" perde gli zeri iniziali. Converti i campi che intendi con (int) invece di usarlo su un intero array.

json_encode restituisce false: trovare l'errore

json_encode() restituisce false quando non riesce a codificare il valore. Le cause abituali sono una stringa che non è UTF-8 valido (testo letto da un vecchio file o da un database Latin-1) e i valori float NAN e INF. json_last_error_msg() dice cosa è andato storto; JSON_THROW_ON_ERROR le fa invece lanciare una JsonException:

<?php
$name = "Caf\xE9";   // "Café" in Latin-1, not valid UTF-8

var_dump(json_encode(['name' => $name]));
echo json_last_error_msg(), "\n";

// Replace the broken bytes instead of failing
echo json_encode(['name' => $name], JSON_INVALID_UTF8_SUBSTITUTE), "\n";

// Or convert the text to UTF-8 first
echo json_encode(['name' => mb_convert_encoding($name, 'UTF-8', 'ISO-8859-1')], JSON_UNESCAPED_UNICODE), "\n";

try {
    json_encode(NAN, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    echo get_class($e), ': ', $e->getMessage(), "\n";
}

Output:

bool(false)
Malformed UTF-8 characters, possibly incorrectly encoded
{"name":"Caf\ufffd"}
{"name":"Café"}
JsonException: Inf and NaN cannot be JSON encoded

JSON_THROW_ON_ERROR è il default migliore nel codice nuovo: un false che nessuno controlla finisce salvato o inviato come stringa vuota.

Restituire JSON da un'API PHP

Uno script PHP che risponde con JSON imposta l'intestazione Content-Type prima di stampare qualsiasi cosa, codifica una volta e si ferma:

<?php
header('Content-Type: application/json; charset=utf-8');

$products = [
    ['id' => 1, 'name' => 'りんご', 'price' => 120],
    ['id' => 2, 'name' => 'みかん', 'price' => 80],
];

echo json_encode(['data' => $products], JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
exit;

Quando invece stampi un JSON dentro un tag HTML <script>, aggiungi JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT. L'escape di default delle barre trasforma </script> in <\/script>, ma quella protezione sparisce appena qualcuno aggiunge JSON_UNESCAPED_SLASHES, e <!-- in un valore cambia comunque il modo in cui il browser analizza lo script. I flag scrivono <, >, &, ' e " come \u003C, \u003E, \u0026, \u0027 e \u0022, che JavaScript rilegge come gli stessi caratteri.

Domande frequenti

Come converto un array PHP in JSON?

Passalo a json_encode(): json_encode(['name' => 'Ada', 'age' => 36]) restituisce {"name":"Ada","age":36}. Un array con chiavi 0, 1, 2... in ordine diventa invece un array JSON: json_encode(['a', 'b']) restituisce ["a","b"].

Come stampo un JSON formattato in PHP?

Aggiungi il flag JSON_PRETTY_PRINT: json_encode($data, JSON_PRETTY_PRINT) indenta con 4 spazi e mette ogni valore su una riga a sé. Combina i flag con |, per esempio JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE.

Perché json_encode trasforma il testo giapponese in codici \u?

Di default ogni carattere non ASCII viene scritto come escape \uXXXX, quindi りんご diventa \u308a\u3093\u3054. È comunque JSON valido, ma passa JSON_UNESCAPED_UNICODE per mantenere leggibili i caratteri.

Perché json_encode restituisce false?

Di solito perché una stringa non è UTF-8 valido, oppure i dati contengono NAN o INF. Chiama json_last_error_msg() per vedere il motivo, oppure passa JSON_THROW_ON_ERROR così lancia una JsonException invece di restituire false.

Come faccio a ottenere {} invece di [] da json_encode per un array vuoto?

Un array PHP vuoto viene sempre codificato come []. Usa new stdClass() o (object) [] per un oggetto vuoto, oppure il flag JSON_FORCE_OBJECT, che trasforma in oggetto ogni array contenuto nel valore.

Concetti correlati