الدالة 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 متداخل

استجابات الواجهات البرمجية عادة قائمة من الكائنات داخل كائن. فك الترميز مرة واحدة، ثم امشِ عليه بـ 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"

علامة ترتيب البايتات غير مرئية في معظم المحررات وهي السبب الكلاسيكي لملف JSON «يبدو سليمًا» لكنه لا يُفك ترميزه. احذفها بـ $text = preg_replace('/^\xEF\xBB\xBF/', '', $text); قبل فك الترميز.