Encodage JSON avec PHP

JSON (JavaScript Object Notation) est un format d'échange de données léger, basé sur du texte, facile à lire pour les humains et facile à analyser pour les machines. C'est le format de facto pour envoyer des données entre un serveur et le navigateur, pour les API REST, et pour les fichiers de configuration. En PHP, json_encode() prend une valeur PHP — un scalaire, un tableau ou un objet — et retourne sa représentation JSON sous forme de chaîne.

Cette page couvre la syntaxe, les $flags les plus utiles, la correspondance des types PHP vers JSON, et la détection des erreurs d'encodage. Pour faire l'opération inverse (chaîne JSON → valeur PHP), consultez json_decode().

Syntaxe

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

La fonction retourne une chaîne encodée en JSON en cas de succès, ou false en cas d'échec (par exemple, lorsque l'entrée contient des caractères UTF-8 mal formés).

Paramètres

• $value — la valeur à encoder. Elle peut être de n'importe quel type sauf un resource. Toutes les données de type string doivent être en UTF-8 valide.
• $flags (optionnel) — un masque de bits qui personnalise la sortie. Les plus courants :
  • JSON_PRETTY_PRINT — ajoute des espaces et une indentation pour rendre la sortie lisible.
  • JSON_UNESCAPED_UNICODE — conserve les caractères multi-octets (é, ñ, 日) tels quels au lieu de les échapper en \uXXXX.
  • JSON_UNESCAPED_SLASHES — laisse / non échappé (PHP l'échappe en \/ par défaut).
  • JSON_FORCE_OBJECT — encode un tableau séquentiel en objet JSON ({}) au lieu d'un tableau ([]).
  • JSON_THROW_ON_ERROR — lève une JsonException en cas d'échec au lieu de retourner false (PHP 7.3+).
  • Combinez les drapeaux avec l'opérateur OR binaire : JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE.
• $depth (optionnel) — la profondeur d'imbrication maximale. Doit être supérieure à 0. La valeur par défaut de 512 est largement suffisante pour des données normales.

Correspondance des types PHP vers JSON

Exemples

Encodage d'un tableau

Un tableau associatif PHP devient un objet JSON ; les clés deviennent des noms de propriétés.

Sortie :

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

Encodage d'un objet

Les propriétés publiques d'un objet sont encodées ; les propriétés private et protected sont ignorées.

Sortie :

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

Affichage formaté et Unicode non échappé

Par défaut, la sortie est compacte, sur une seule ligne, et les caractères non-ASCII sont échappés (ainsi é devient é). Deux drapeaux rendent la sortie lisible par l'humain :

<?php

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

echo json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);

?>

Sortie :

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

Notez que 9.50 est émis comme 9.5 — les zéros de fin sur les flottants sont supprimés. Utilisez JSON_PRESERVE_ZERO_FRACTION si vous avez besoin que 9.0 reste un flottant plutôt que de devenir 9.

Gestion des erreurs

Si json_encode() retourne false, quelque chose s'est mal passé — le plus souvent un UTF-8 mal formé dans une chaîne. Vérifiez json_last_error_msg(), ou passez JSON_THROW_ON_ERROR pour obtenir une exception à la place.

<?php

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

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

?>

Sortie :

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

Cas d'utilisation courants

• Retourner des données depuis une API. Définissez l'en-tête et affichez le tableau encodé :

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

  Copier

• Stocker des données structurées dans un fichier ou une colonne texte d'une base de données à la place de serialize(). JSON est portable entre les langages ; serialize() est spécifique à PHP.

• Transmettre des données à JavaScript rendu sur la page, car un JSON valide est une syntaxe d'objet JavaScript valide.

Conclusion

json_encode() transforme les tableaux et objets PHP en une chaîne JSON compacte et portable. Utilisez JSON_PRETTY_PRINT et JSON_UNESCAPED_UNICODE lorsqu'un humain lira la sortie, protégez-vous contre les entrées mal formées en vérifiant la valeur de retour ou en utilisant JSON_THROW_ON_ERROR, et rappelez-vous que seules les propriétés publiques des objets sont encodées. Pour analyser du JSON en PHP, utilisez json_decode() ; pour une vue d'ensemble plus large, consultez Travailler avec JSON en PHP.

Pratique