Référence des fonctions JSON en PHP

JSON (JavaScript Object Notation) est un format d'échange de données léger et textuel. Comme il est facile à lire pour les humains et trivial à analyser pour les machines, il est devenu le moyen standard d'envoyer des données entre un serveur et un navigateur, ainsi qu'entre les services web (API REST).

PHP est livré avec un petit ensemble de fonctions intégrées — collectivement appelées l'extension JSON — qui convertissent les valeurs PHP en texte JSON et inversement. Cette page est une référence rapide à ces fonctions et aux constantes d'options les plus utiles. Pour un tutoriel étape par étape, consultez PHP JSON.

Quand utiliser JSON en PHP ?

Ces fonctions sont utiles dès que des données doivent quitter PHP sous forme de texte ou arriver sous forme de texte :

• Retourner des données depuis un point d'accès API (echo json_encode($data);).
• Lire un corps de requête ou un fichier de configuration écrit en JSON.
• Stocker une valeur structurée (un tableau de paramètres, par exemple) dans une seule colonne de base de données ou une clé de cache.
• Communiquer avec un service web tiers qui utilise JSON.

L'extension JSON est activée par défaut dans PHP 5.2 et versions ultérieures, et fait partie du cœur de PHP 8.0+, donc aucune installation n'est nécessaire.

Fonctions JSON

json_encode()

json_encode() sérialise une valeur PHP en une chaîne au format JSON.

<?php

$data = [
    "name"  => "Ada",
    "age"   => 36,
    "langs" => ["PHP", "JS"],
];

echo json_encode($data);

?>

Résultat :

{"name":"Ada","age":36,"langs":["PHP","JS"]}

Notez comment un tableau associatif devient un objet JSON {}, tandis qu'un tableau de liste (["PHP","JS"]) devient un tableau JSON []. Consultez la référence complète dans json_encode().

Affichage formaté du résultat

Passez l'option JSON_PRETTY_PRINT pour rendre le résultat lisible :

<?php

$data = ["name" => "Ada", "langs" => ["PHP", "JS"]];

echo json_encode($data, JSON_PRETTY_PRINT);

?>

Résultat :

{
    "name": "Ada",
    "langs": [
        "PHP",
        "JS"
    ]
}

json_decode()

json_decode() analyse une chaîne JSON et la transforme en valeur PHP. Par défaut, elle retourne des objets (stdClass) ; passez true comme second argument pour obtenir des tableaux associatifs à la place.

<?php

$json = '{"name":"Ada","age":36,"langs":["PHP","JS"]}';

// Decode as an associative array
$data = json_decode($json, true);

echo $data["name"];   // Ada
echo "\n";
echo $data["langs"][0]; // PHP

?>

Résultat :

Ada
PHP

Consultez la référence complète dans json_decode().

Gestion des erreurs

json_encode() retourne false et json_decode() retourne null lorsque quelque chose tourne mal (UTF-8 invalide, erreur de syntaxe dans l'entrée, ou imbrication dépassant la limite de profondeur). Comme null est aussi une valeur décodée valide, vérifiez toujours json_last_error() plutôt que de tester uniquement null.

<?php

$bad = '{"name": "Ada", }';   // trailing comma is invalid JSON

$result = json_decode($bad, true);

if (json_last_error() !== JSON_ERROR_NONE) {
    echo "Invalid JSON: " . json_last_error_msg();
} else {
    echo "Decoded fine.";
}

?>

Résultat :

Invalid JSON: Syntax error

En PHP 7.3+, vous pouvez passer le drapeau JSON_THROW_ON_ERROR aux deux fonctions pour obtenir une JsonException au lieu d'inspecter manuellement le code d'erreur.

Constantes d'options courantes

Ces constantes de masque de bits sont passées dans l'argument $options de json_encode() (et certaines s'appliquent également à json_decode()) :

• JSON_PRETTY_PRINT — formate le résultat avec des espaces et une indentation.
• JSON_UNESCAPED_SLASHES — laisse les caractères / non échappés (http:// au lieu de http:\/\/).
• JSON_UNESCAPED_UNICODE — conserve les caractères multi-octets tels quels au lieu des séquences d'échappement \uXXXX.
• JSON_THROW_ON_ERROR — lève une JsonException en cas d'échec (PHP 7.3+).
• JSON_FORCE_OBJECT — émet toujours un objet JSON, même pour un tableau séquentiel.

Combinez-les avec l'opérateur OR binaire :

<?php

$data = ["site" => "https://www.w3docs.com", "name" => "café"];

echo json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);

?>

Résultat :

{
    "site": "https://www.w3docs.com",
    "name": "café"
}

Sujets connexes

• PHP JSON — l'introduction complète sous forme de tutoriel.
• PHP Arrays et Tableaux associatifs — les structures qui correspondent le plus naturellement à JSON.
• PHP Functions — comment encapsuler l'encodage/décodage dans vos propres fonctions utilitaires.

Entraînement