json_decode() ב-PHP: פענוח JSON למערכים או לאובייקטים

json_decode($json, true) הופכת מחרוזת JSON לערכי PHP, כשכל אובייקט JSON הופך למערך אסוציאטיבי. השמיטו את true ואובייקטי JSON יהפכו במקום זאת לאובייקטי stdClass, שקוראים עם ->. JSON לא תקין נותן 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);

פלט:

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

    [admin] => 1
)

מערכי JSON תמיד הופכים לרשימות PHP, בכל מצב שתבחרו. הכיוון ההפוך, מ-PHP ל-JSON, הוא json_encode().

מערך אסוציאטיבי או אובייקט: true מול false

שני המצבים מחזיקים את אותם נתונים; בחרו את זה שנקרא טוב יותר בקוד שלכם. מערכים עובדים עם כל פונקציית מערך (array_column, array_map, isset($data['key'])), ולכן רוב הקוד מעביר true. אובייקטים צריכים את תחביר הסוגריים המסולסלים למפתחות שאינם שמות מאפיינים תקינים, כמו מפתחות עם מקף או מספר:

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

פלט:

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

הפרמטר הרביעי מקבל דגלים. JSON_OBJECT_AS_ARRAY נותן גם הוא מערכים, אבל רק כל עוד הארגומנט השני הוא null (ברירת המחדל שלו): json_decode($json, flags: JSON_OBJECT_AS_ARRAY) מחזירה מערכים, בעוד json_decode($json, false, 512, JSON_OBJECT_AS_ARRAY) עדיין מחזירה אובייקטים.

מעבר על JSON מקונן

תשובות של API הן בדרך כלל רשימה של אובייקטים בתוך אובייקט. פענחו פעם אחת, ואז עברו עליה עם foreach, והשתמשו ב-?? לשדות שעשויים לחסור:

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

פלט:

#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
)

טיפול ב-JSON לא תקין

json_decode() מחזירה null ל-JSON לא תקין, אבל null הוא גם התוצאה הנכונה לטקסט ה-JSON null, ולכן null לבדו לא אומר לכם אם היא נכשלה. json_last_error_msg() נותנת את הסיבה של הקריאה האחרונה. הדרך הנקייה יותר היא JSON_THROW_ON_ERROR, שזורק 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";
}

פלט:

NULL
Syntax error
NULL
No error
Invalid JSON: Syntax error

הארגומנט השלישי, 512, הוא עומק הקינון המקסימלי (ברירת המחדל). עם ארגומנטים בשם אפשר לדלג עליו: json_decode($json, true, flags: JSON_THROW_ON_ERROR).

בדיקה אם מחרוזת היא JSON תקין עם json_validate()

PHP 8.3 הוסיפה את json_validate(). היא עונה true או false בלי לבנות את המערכים המפוענחים, ולכן היא משתמשת בפחות זיכרון מפענוח כשכל מה שצריך הוא כן או לא, למשל כדי לדחות גוף בקשה מוקדם:

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

פלט:

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

אם תשתמשו בנתונים בכל מקרה, דלגו על json_validate() ופענחו עם JSON_THROW_ON_ERROR: אימות קודם מפענח את המחרוזת פעמיים.

קריאת קובץ JSON

קראו את הקובץ עם file_get_contents() ופענחו את המחרוזת. הבלוק הזה כותב קודם את settings.json כדי שיהיה קובץ לקרוא:

<?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";

פלט:

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

למה json_decode מחזירה null: הסיבות הרגילות

JSON מחמיר יותר מתחביר המערכים של JavaScript ושל PHP. כל מחרוזת למטה נראית סבירה וכל אחת מחזירה null. הריצו כדי לראות את הסיבה לכל אחת, ואז תקנו אחת והריצו שוב:

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

פלט:

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"

byte order mark בלתי נראה ברוב העורכים, והוא הסיבה הקלאסית לכך שקובץ JSON "נראה בסדר" אבל לא מתפענח. הסירו אותו עם $text = preg_replace('/^\xEF\xBB\xBF/', '', $text); לפני הפענוח.