PHP json_encode() : convertir tableaux et objets en JSON

Q: Comment convertir un tableau PHP en JSON ?

Passez-le à jsonencode() : jsonencode(['name' => 'Ada', 'age' => 36]) renvoie {"name":"Ada","age":36}. Un tableau aux clés 0, 1, 2... dans l'ordre devient plutôt un tableau JSON : json_encode(['a', 'b']) renvoie ["a","b"].

Q: Comment afficher du JSON indenté en PHP ?

Ajoutez l'option JSONPRETTYPRINT : jsonencode($data, JSONPRETTYPRINT) indente avec 4 espaces et place chaque valeur sur sa propre ligne. Combinez les options avec |, par exemple JSONPRETTYPRINT | JSONUNESCAPED_UNICODE.

Q: Comment faire sortir {} au lieu de [] pour un tableau vide avec json_encode ?

Un tableau PHP vide s'encode toujours en []. Utilisez new stdClass() ou (object) [] pour un objet vide, ou l'option JSONFORCEOBJECT, qui transforme chaque tableau de la valeur en objet.

json_encode($value) renvoie le texte JSON d'une valeur PHP. Un tableau associatif devient un objet JSON, une liste (clés 0, 1, 2...) devient un tableau JSON, et les chaînes, nombres, true, false et null deviennent leurs équivalents 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";

Sortie :

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

Le résultat est une simple chaîne, prête à être envoyée à un navigateur, enregistrée dans un fichier ou une colonne de base de données, ou transmise à un autre programme. Pour retransformer du JSON en PHP, utilisez json_decode().

Indenter le JSON

json_encode() prend des options en second argument. JSON_PRETTY_PRINT ajoute des sauts de ligne et une indentation de 4 espaces, ce qu'il vous faut dans un fichier de configuration ou un journal de débogage. Combinez plusieurs options avec | :

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

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

Sortie :

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

Garder lisibles les accents, le japonais et les autres textes UTF-8

Par défaut, json_encode() écrit chaque caractère non ASCII sous la forme d'un échappement \u et place une barre oblique inverse devant chaque /. Les deux sont du JSON valide et se décodent en le même texte, mais ils rendent la sortie difficile à lire et plus longue. JSON_UNESCAPED_UNICODE garde les caractères, et JSON_UNESCAPED_SLASHES garde les URL telles quelles :

<?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";

Sortie :

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

Si du texte accentué ou japonais apparaît déformé après décodage, le problème ne vient pas des échappements : la chaîne n'était pas en UTF-8 au départ. json_encode() n'accepte que l'UTF-8 et renvoie false pour tout le reste, comme le montre la section sur les erreurs.

Quand un tableau devient un objet au lieu d'une liste

Un tableau PHP n'est encodé en tableau JSON que si ses clés sont exactement 0, 1, 2... dans l'ordre. Toute autre clé en fait un objet JSON. Cela piège après unset() ou array_filter(), qui laissent des trous dans les clés :

<?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";

Sortie :

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

Appelez array_values() avant l'encodage chaque fois que le code destinataire attend une liste. S'il attend un objet qui peut être vide, utilisez new stdClass() ou (object) $array pour qu'une valeur vide sorte quand même en {}.

Encoder un objet et contrôler son JSON avec JsonSerializable

Un objet simple est encodé avec ses propriétés publiques seulement ; les propriétés protégées et privées sont ignorées. Pour décider exactement de l'allure d'un objet en JSON, implémentez l'interface JsonSerializable et renvoyez les données depuis 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";

Sortie :

{"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"
}

Une enum adossée comme enum Status: string s'encode sous forme de sa valeur ("active"). Une enum pure n'a pas de valeur, donc json_encode() échoue dessus avec « Non-backed enums have no default serialization ».

Nombres, floats et chaînes numériques

Les entiers et les floats sont écrits comme des nombres JSON, et les chaînes restent des chaînes même si elles contiennent des chiffres. Trois options changent cela :

<?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";

Sortie :

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

JSON_NUMERIC_CHECK convertit chaque chaîne numérique, donc un identifiant comme "007" ou un code postal comme "01234" perd ses zéros initiaux. Convertissez les champs voulus avec (int) au lieu de l'appliquer à tout un tableau.

json_encode renvoie false : trouver l'erreur

json_encode() renvoie false quand il ne peut pas encoder la valeur. Les causes habituelles sont une chaîne qui n'est pas en UTF-8 valide (du texte lu dans un vieux fichier ou une base Latin-1) et les valeurs float NAN et INF. json_last_error_msg() indique ce qui n'a pas marché ; JSON_THROW_ON_ERROR lui fait plutôt lever une 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";
}

Sortie :

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 est le meilleur choix par défaut dans du code neuf : un false que personne ne vérifie finit stocké ou envoyé sous forme de chaîne vide.

Renvoyer du JSON depuis une API PHP

Un script PHP qui répond en JSON définit l'en-tête Content-Type avant d'afficher quoi que ce soit, encode une seule fois, puis s'arrête :

<?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;

Quand vous affichez plutôt du JSON dans une balise HTML <script>, ajoutez JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT. L'échappement par défaut des barres obliques transforme </script> en <\/script>, mais cette protection disparaît dès que quelqu'un ajoute JSON_UNESCAPED_SLASHES, et un <!-- dans une valeur change toujours la façon dont le navigateur analyse le script. Ces options écrivent <, >, &, ' et " sous la forme \u003C, \u003E, \u0026, \u0027 et \u0022, que JavaScript relit comme les mêmes caractères.

Questions fréquentes

Comment convertir un tableau PHP en JSON ?

Passez-le à json_encode() : json_encode(['name' => 'Ada', 'age' => 36]) renvoie {"name":"Ada","age":36}. Un tableau aux clés 0, 1, 2... dans l'ordre devient plutôt un tableau JSON : json_encode(['a', 'b']) renvoie ["a","b"].

Comment afficher du JSON indenté en PHP ?

Ajoutez l'option JSON_PRETTY_PRINT : json_encode($data, JSON_PRETTY_PRINT) indente avec 4 espaces et place chaque valeur sur sa propre ligne. Combinez les options avec |, par exemple JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE.

Pourquoi json_encode transforme-t-il les caractères accentués ou japonais en codes \u ?

Par défaut, chaque caractère non ASCII est écrit sous la forme d'un échappement \uXXXX, donc りんご devient \u308a\u3093\u3054. C'est toujours du JSON valide, mais passez JSON_UNESCAPED_UNICODE pour garder les caractères lisibles.

Pourquoi json_encode renvoie-t-il false ?

En général parce qu'une chaîne n'est pas en UTF-8 valide, ou que les données contiennent NAN ou INF. Appelez json_last_error_msg() pour voir la raison, ou passez JSON_THROW_ON_ERROR pour qu'il lève une JsonException au lieu de renvoyer false.

Comment faire sortir {} au lieu de [] pour un tableau vide avec json_encode ?

Un tableau PHP vide s'encode toujours en []. Utilisez new stdClass() ou (object) [] pour un objet vide, ou l'option JSON_FORCE_OBJECT, qui transforme chaque tableau de la valeur en objet.

Concepts liés