PHP JSON

JSON (JavaScript Object Notation) est un format d'échange de données léger et textuel. C'est le moyen le plus courant d'envoyer et de recevoir des données entre un backend PHP et un navigateur, une application mobile ou un autre service web (la plupart des API REST utilisent JSON). Ce guide couvre tout ce dont vous avez besoin pour travailler avec JSON en PHP : convertir des données PHP en JSON avec json_encode, reconvertir du JSON en données PHP avec json_decode, formater la sortie et gérer les erreurs de manière sûre.

PHP intègre la prise en charge de JSON dans son noyau (l'extension ext-json est incluse et activée par défaut depuis PHP 8.0), il n'y a donc rien à installer.

À quoi ressemble JSON

JSON représente les données sous forme de paires clé-valeur à l'intérieur d'objets ({ }) et de listes ordonnées à l'intérieur de tableaux ([ ]). Les valeurs peuvent être des chaînes, des nombres, des booléens, null, des tableaux ou des objets imbriqués :

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

Les deux fonctions que vous utiliserez presque à chaque fois sont :

• json_encode($value) — valeur PHP → chaîne JSON (sérialisation).
• json_decode($json) — chaîne JSON → valeur PHP (désérialisation).

Encodage : PHP vers JSON avec json_encode

json_encode() convertit une valeur PHP — généralement un tableau ou un objet — en chaîne JSON.

Encodage d'un tableau associatif

Un tableau associatif devient un objet JSON, tandis qu'un tableau indexé (clés entières séquentielles commençant à 0) devient un tableau JSON :

<?php

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

?>

Formatage de la sortie

Par défaut, json_encode produit du JSON compact sur une seule ligne, ce qui est idéal pour l'envoi sur le réseau. Lorsque vous souhaitez une sortie lisible (pour la journalisation ou le débogage), passez le drapeau JSON_PRETTY_PRINT. Les drapeaux se combinent avec l'opérateur bitwise | :

<?php

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

echo json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);

?>

Cela affiche du JSON bien indenté :

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

Autres drapeaux utiles : JSON_UNESCAPED_SLASHES (conserve / au lieu de \/) et JSON_UNESCAPED_UNICODE (conserve des caractères comme é au lieu de é).

Décodage : JSON vers PHP avec json_decode

json_decode() convertit une chaîne JSON en valeur PHP. Par défaut, elle retourne des objets, mais passer true comme second argument retourne des tableaux associatifs à la place — ce qui est généralement plus facile à parcourir :

Sans l'argument true, vous obtenez un objet stdClass et accédez aux valeurs avec la notation flèche -> au lieu de [ ] :

Utilisez true lorsque vous souhaitez un tableau ; omettez-le lorsque vous préférez la syntaxe objet. Les deux contiennent les mêmes données.

Encodage d'un objet personnalisé

json_encode fonctionne également sur les objets. Lorsque vous avez besoin de construire une structure JSON à la volée, l'objet stdClass vide vous permet d'attacher des propriétés dynamiquement. (Pour les classes complètes, voir PHP Classes et Objets.)

Les propriétés publiques de tout objet sont incluses automatiquement ; les propriétés privées et protégées sont ignorées à moins que la classe n'implémente l'interface JsonSerializable.

Gestion des erreurs

L'analyse JSON peut échouer — une chaîne malformée, un guillemet non fermé ou une virgule en fin de liste vont tous interrompre le décodage. Quand json_decode échoue, il retourne null, vous devez donc distinguer une vraie valeur null d'une erreur. Vérifiez json_last_error() (ou lisez json_last_error_msg() pour un message lisible) :

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

?>

Depuis PHP 7.3, vous pouvez à la place passer le drapeau JSON_THROW_ON_ERROR pour que les deux fonctions lèvent une JsonException, ce qui s'intègre proprement dans des blocs try/catch :

<?php

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

?>

Remarque : json_decode a une limite de profondeur (512 niveaux par défaut, le troisième argument). Du JSON très profondément imbriqué échouera avec une erreur JSON_ERROR_DEPTH sauf si vous augmentez cette valeur.

Cas d'utilisation courant : lire un corps de requête JSON

Lorsqu'un client envoie du JSON à un point d'entrée PHP (comme la plupart des API le font), le corps arrive en tant qu'entrée brute plutôt que via $_POST. Lisez-le avec php://input et décodez-le :

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

?>

Conclusion

JSON est le format standard pour l'échange de données dans les applications web modernes, et PHP le rend simple à utiliser :

• Utilisez json_encode pour convertir des tableaux et des objets en JSON ; ajoutez JSON_PRETTY_PRINT pour une sortie lisible.
• Utilisez json_decode pour reconvertir du JSON en PHP — passez true pour un tableau, omettez-le pour un objet.
• Vérifiez toujours les erreurs avec json_last_error() ou JSON_THROW_ON_ERROR avant de faire confiance aux données décodées.

Avec ces outils, vous pouvez envoyer et recevoir du JSON en toute confiance entre votre code PHP, vos bases de données, vos navigateurs et les services web externes.

Pratique