Comprendre la fonction json_decode en PHP

La fonction json_decode en PHP transforme une chaîne au format JSON en valeur PHP native que vous pouvez lire et manipuler. Elle est le pendant de json_encode, qui fait l'inverse (valeur PHP → chaîne JSON). On utilise json_decode chaque fois que des données arrivent sous forme de texte et qu'on doit les exploiter : réponse d'une API REST, payload de webhook, fichier de configuration ou colonne stockée en base de données.

Ce chapitre couvre la signature de la fonction, la différence entre le décodage vers un objet et vers un tableau associatif, le comportement des données imbriquées, les options de profondeur et les indicateurs, ainsi que la bonne façon de gérer les entrées invalides.

Qu'est-ce que JSON ?

JSON (JavaScript Object Notation) est un format d'échange de données léger et textuel, facile à lire pour les humains et à analyser pour les machines. Il représente les données sous forme de paires clé-valeur (objets, notés {}) et de listes ordonnées (tableaux, notés []), avec des chaînes, des nombres, des booléens et null comme valeurs scalaires. Comme presque tous les langages peuvent le produire et le consommer, JSON est devenu le format par défaut pour les API web. Consultez la vue d'ensemble de PHP et JSON pour une présentation plus complète.

Syntaxe

json_decode(string $json, ?bool $associative = null, int $depth = 512, int $flags = 0): mixed

Paramètre	Rôle
`$json`	La chaîne JSON à décoder. Doit être en UTF-8 valide.
`$associative`	`true` → retourne des tableaux associatifs ; `false`/`null` → retourne des objets `stdClass`.
`$depth`	Profondeur d'imbrication maximale autorisée (par défaut `512`). Le décodage échoue si l'entrée est plus profonde.
`$flags`	Masque de bits d'options, par ex. `JSON_THROW_ON_ERROR`, `JSON_BIGINT_AS_STRING`.

La fonction retourne la valeur décodée (array, stdClass, string, int, float, bool ou null), ou null en cas d'échec.

Décoder une chaîne JSON

L'utilisation la plus courante est le décodage d'un objet JSON. Passez true comme second argument pour obtenir un tableau associatif PHP en retour.

Exemple de la fonction PHP json_decode

php— editable, runs on the server

Ici $json représente le nom, l'âge et la ville d'une personne. Avec true, json_decode construit un tableau PHP, et le résultat est :

Array
(
    [name] => John
    [age] => 30
    [city] => New York
)

Vous lisez ensuite les valeurs avec la syntaxe de tableau, par ex. $array['name']. Consultez les tableaux associatifs pour en savoir plus sur cette structure de données.

Utiliser le deuxième paramètre

Le deuxième paramètre de la fonction json_decode est facultatif, mais il est souvent utilisé pour contrôler le type de la variable retournée. S'il est défini à true, json_decode retourne un tableau. S'il est défini à false (la valeur par défaut), json_decode retourne un objet.

Exemple de la fonction PHP json_decode avec des objets

php— editable, runs on the server

Lorsque $associative est false (ou omis), json_decode retourne un objet stdClass. Vous lisez les valeurs avec la syntaxe de propriété objet $object->name, $object->age, etc. Utilisez cette forme lorsque vous préférez l'accès par propriétés ou lorsque le résultat sera transmis à du code qui attend des objets (voir les classes et objets PHP).

Décoder du JSON imbriqué

En pratique, le JSON est généralement imbriqué. json_decode gère l'imbrication automatiquement : chaque niveau devient un tableau imbriqué (avec true) ou un objet imbriqué (avec false).

<?php

$json = '{"user":{"name":"John","roles":["admin","editor"]}}';
$data = json_decode($json, true);

echo $data['user']['name'];      // John
echo "\n";
echo $data['user']['roles'][0];  // admin

?>

Les objets JSON internes deviennent des tableaux internes, et les tableaux JSON ([...]) deviennent des tableaux PHP indexés que vous pouvez parcourir avec foreach.

Gestion des erreurs

Si la chaîne passée à json_decode n'est pas un JSON valide, la fonction retourne null. Cependant, null est aussi une valeur JSON valide, donc vérifier if ($array === null) ne permet pas de distinguer une erreur de décodage d'un décodage réussi du littéral null. Pour gérer correctement les erreurs, vérifiez json_last_error() ou utilisez l'indicateur JSON_THROW_ON_ERROR (PHP 7.3+).

Gérer les erreurs de json_decode en PHP

php— editable, runs on the server

La chaîne ci-dessus est privée d'un guillemet fermant, donc json_last_error() n'est pas JSON_ERROR_NONE et le message explique ce qui s'est passé.

À partir de PHP 7.3, l'option la plus propre est l'indicateur JSON_THROW_ON_ERROR, qui lève une JsonException au lieu de retourner silencieusement null :

<?php

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

?>

Cela vous permet de gérer les entrées malformées avec des blocs try/catch standard au lieu de vérifier le résultat manuellement après chaque appel.

Fonctions associées

json_encode — convertir une valeur PHP en chaîne JSON.
PHP et JSON — vue d'ensemble du travail avec JSON en PHP.
Référence JSON PHP — liste complète des fonctions et constantes JSON de PHP.

Conclusion

La fonction json_decode en PHP est un outil puissant pour travailler avec des données JSON. Elle est rapide, fiable et facile à utiliser. En comprenant les détails de json_decode et de son deuxième paramètre, vous pouvez décoder des chaînes JSON en toute confiance et utiliser les données résultantes dans vos applications PHP.

Pratique

Que fait la fonction json_decode() en PHP ?

Elle convertit une chaîne JSON en variable PHP.Elle décode des données encodées en base64.Elle transforme les caractères HTML en entités.Elle permet de passer true comme second argument pour convertir les objets JSON en tableaux associatifs.