PHP json_decode() : lire du JSON en tableau ou en objet

json_decode($json, true) transforme une chaîne JSON en valeurs PHP, chaque objet JSON devenant un tableau associatif. Omettez true et les objets JSON deviennent plutôt des objets stdClass, lus avec ->. Un JSON invalide donne null.

<?php
$json = '{"name": "Ada", "age": 36, "langs": ["php", "js"], "admin": true}';

$data = json_decode($json, true);   // associative array
echo $data['name'], "\n";
echo $data['langs'][1], "\n";

$obj = json_decode($json);          // stdClass object
echo $obj->name, "\n";
echo $obj->langs[0], "\n";

print_r($data);

Sortie :

Ada
js
Ada
php
Array
(
    [name] => Ada
    [age] => 36
    [langs] => Array
        (
            [0] => php
            [1] => js
        )

    [admin] => 1
)

Les tableaux JSON deviennent toujours des listes PHP, quel que soit le mode choisi. Dans l'autre sens, de PHP vers JSON, c'est json_encode().

Tableau associatif ou objet : true ou false

Les deux modes contiennent les mêmes données ; choisissez celui qui se lit le mieux dans votre code. Les tableaux fonctionnent avec toutes les fonctions de tableau (array_column, array_map, isset($data['key'])), c'est pourquoi la plupart du code passe true. Les objets demandent la syntaxe à accolades pour les clés qui ne sont pas des noms de propriété valides, comme les clés avec un tiret ou un nombre :

<?php
$json = '{"first-name": "Ada", "0": "zero", "address": {"city": "London"}}';

$arr = json_decode($json, true);
echo $arr['first-name'], ' ', $arr[0], ' ', $arr['address']['city'], "\n";

$obj = json_decode($json);
echo $obj->{'first-name'}, ' ', $obj->{'0'}, ' ', $obj->address->city, "\n";

var_dump($obj->address);

Sortie :

Ada zero London
Ada zero London
object(stdClass)#2 (1) {
  ["city"]=>
  string(6) "London"
}

Le quatrième paramètre prend des options. JSON_OBJECT_AS_ARRAY donne aussi des tableaux, mais seulement tant que le second argument vaut null (sa valeur par défaut) : json_decode($json, flags: JSON_OBJECT_AS_ARRAY) renvoie des tableaux, alors que json_decode($json, false, 512, JSON_OBJECT_AS_ARRAY) renvoie toujours des objets.

Parcourir du JSON imbriqué

Les réponses d'API sont en général une liste d'objets dans un objet. Décodez une fois, puis parcourez avec foreach, et utilisez ?? pour les champs qui peuvent manquer :

<?php
$json = <<<'JSON'
{
    "page": 1,
    "users": [
        {"id": 1, "name": "Ada", "email": "ada@example.com", "roles": ["admin", "editor"]},
        {"id": 2, "name": "Linus", "roles": []},
        {"id": 3, "name": "Grace", "email": "grace@example.com", "roles": ["editor"]}
    ]
}
JSON;

$data = json_decode($json, true);

foreach ($data['users'] as $user) {
    $email = $user['email'] ?? 'no email';
    $roles = $user['roles'] ? implode(', ', $user['roles']) : 'none';
    echo "#{$user['id']} {$user['name']} <$email> roles: $roles\n";
}

$names = array_column($data['users'], 'name', 'id');
print_r($names);

Sortie :

#1 Ada <ada@example.com> roles: admin, editor
#2 Linus <no email> roles: none
#3 Grace <grace@example.com> roles: editor
Array
(
    [1] => Ada
    [2] => Linus
    [3] => Grace
)

Gérer un JSON invalide

json_decode() renvoie null pour un JSON invalide, mais null est aussi le bon résultat pour le texte JSON null, donc null seul ne dit pas si le décodage a échoué. json_last_error_msg() donne la raison du dernier appel. La façon plus propre est JSON_THROW_ON_ERROR, qui lève une JsonException :

<?php
var_dump(json_decode('{"a": 1,}'));   // trailing comma
echo json_last_error_msg(), "\n";

var_dump(json_decode('null'));        // valid JSON, also null
echo json_last_error_msg(), "\n";

try {
    $data = json_decode("{'a': 1}", true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    echo 'Invalid JSON: ', $e->getMessage(), "\n";
}

Sortie :

NULL
Syntax error
NULL
No error
Invalid JSON: Syntax error

Le troisième argument, 512, est la profondeur d'imbrication maximale (la valeur par défaut). Avec les arguments nommés, vous pouvez le sauter : json_decode($json, true, flags: JSON_THROW_ON_ERROR).

Vérifier si une chaîne est du JSON valide avec json_validate()

PHP 8.3 a ajouté json_validate(). Elle répond true ou false sans construire les tableaux décodés, elle utilise donc moins de mémoire que le décodage quand vous n'avez besoin que d'un oui ou d'un non, par exemple pour rejeter tôt le corps d'une requête :

<?php
$inputs = ['{"a": 1}', '[1, 2, 3]', '"text"', '{a: 1}', "{'a': 1}", ''];

foreach ($inputs as $input) {
    $ok = json_validate($input) ? 'valid' : 'invalid: ' . json_last_error_msg();
    echo str_pad(var_export($input, true), 14), $ok, "\n";
}

Sortie :

'{"a": 1}'    valid
'[1, 2, 3]'   valid
'"text"'      valid
'{a: 1}'      invalid: Syntax error
'{\'a\': 1}'  invalid: Syntax error
''            invalid: Syntax error

Si vous allez de toute façon utiliser les données, sautez json_validate() et décodez avec JSON_THROW_ON_ERROR : valider d'abord analyse la chaîne deux fois.

Lire un fichier JSON

Lisez le fichier avec file_get_contents() et décodez la chaîne. Ce bloc écrit d'abord settings.json pour qu'il y ait un fichier à lire :

<?php
file_put_contents('settings.json', '{"theme": "dark", "fontSize": 14, "plugins": ["git", "lint"]}');

$text = file_get_contents('settings.json');
if ($text === false) {
    exit("Cannot read settings.json\n");
}

$settings = json_decode($text, true, flags: JSON_THROW_ON_ERROR);
echo "Theme: {$settings['theme']}\n";
echo "Plugins: ", count($settings['plugins']), "\n";

// Change a value and write the file back
$settings['fontSize'] = 16;
file_put_contents('settings.json', json_encode($settings, JSON_PRETTY_PRINT));
echo file_get_contents('settings.json'), "\n";

Sortie :

Theme: dark
Plugins: 2
{
    "theme": "dark",
    "fontSize": 16,
    "plugins": [
        "git",
        "lint"
    ]
}

Pourquoi json_decode renvoie null : les causes habituelles

Le JSON est plus strict que la syntaxe des tableaux JavaScript et PHP. Chaque chaîne ci-dessous semble raisonnable et chacune renvoie null. Exécutez-le pour voir la raison de chacune, puis corrigez-en une et relancez :

<?php
$cases = [
    'single quotes'   => "{'name': 'Ada'}",
    'unquoted key'    => '{name: "Ada"}',
    'trailing comma'  => '{"name": "Ada",}',
    'comment'         => '{"name": "Ada" /* admin */}',
    'byte order mark' => "\xEF\xBB\xBF" . '{"name": "Ada"}',
    'too deep'        => '[[["Ada"]]]',
];

foreach ($cases as $label => $json) {
    $depth = $label === 'too deep' ? 2 : 512;
    $result = json_decode($json, true, $depth);
    echo str_pad($label, 17), $result === null ? json_last_error_msg() : 'ok', "\n";
}

// Big integers lose precision unless you ask for strings
var_dump(json_decode('{"id": 12345678901234567890}', true)['id']);
var_dump(json_decode('{"id": 12345678901234567890}', true, 512, JSON_BIGINT_AS_STRING)['id']);

Sortie :

single quotes    Syntax error
unquoted key     Syntax error
trailing comma   Syntax error
comment          Syntax error
byte order mark  Syntax error
too deep         Maximum stack depth exceeded
float(1.2345678901234567E+19)
string(20) "12345678901234567890"

Une marque d'ordre des octets (BOM) est invisible dans la plupart des éditeurs et c'est la raison classique pour laquelle un fichier JSON « a l'air correct » mais refuse de se décoder. Retirez-la avec $text = preg_replace('/^\xEF\xBB\xBF/', '', $text); avant de décoder.