الدالة json_decode()‎ في PHP

(PHP 5 >= 5.2.0, PHP 7, PECL json >= 1.2.0)

تفك الدالة json_decode()‎ ترميز سلسلة نصية بصيغة JSON.

الوصف

mixed json_decode ( string $json [, bool $assoc = FALSE [, int $depth = 512 [, int $options = 0]]] )

تأخذ سلسلة مُرمَّزة بصيغة JSON وتحوِّلها إلى مُتغيِّر PHP.

المعاملات

json

سلسلة نصية بصيغة JSON التي سيُفكُّ ترميزها.

تعمل هذه الدّالّة مع سلاسل نصّيّة مُرمَّزة بترميز UTF-8 فقط.

ملاحظة: تعتمد PHP مجموعة عُليا من JSON كما هو مُحدَّد في المعيار الأصلي RFC 7159.

assoc

عندما تكون قيمته صحيحة TRUE، فستُحوَّل الكائنات المُعادة من الدّالّة إلى مصفوفات ترابطية (associative arrays).

depth

عُمق المُعاوَدة (recursion) المُحدَّد من قبل المستخدم.

options

خيارات لفك ترميز JSON على شكل قناع بت Bitmask. هناك حاليًّا خياران مدعومان، الأوّل هو JSON_BIGINT_AS_STRING والذي يسمح بقلب الأعداد الصّحيحة الكبيرة إلى سلاسل نصّيّة بدلًا من أعداد ذات فاصلة عائمة float، وهو الخيار الافتراضي، الخيار الثّاني هو JSON_OBJECT_AS_ARRAY وله نفس تأثير تعيين قيمة المُعامِل assoc إلى TRUE.

القيم المعادة

تُعيد هذه الدّالّة القيمة المُرمَّزة في المُعامِل json إلى نوع مناسب في لغة PHP، تُعاد القيم true و false و null على شكل TRUE و FALSE و NULL على التوالي وبالتّرتيب. تُعاد القيمة NULL في حال تعذّر فك ترميز سلسلة JSON أو كانت البيانات المُرمَّزة أعمق من حدّ المُعاوَدة.

أمثلة

المثال 1: أمثلة على استخدام الدالة json_decode()‎

<?php
$json = '{"a":1,"b":2,"c":3,"d":4,"e":5}';
var_dump(json_decode($json));
var_dump(json_decode($json, true));
?>

ينتج عن المثال السّابق ما يلي:

object(stdClass)#1 (5) {
 	["a"] => int(1)
 	["b"] => int(2)
 	["c"] => int(3)
 	["d"] => int(4)
 	["e"] => int(5)
}

array(5) {
 	["a"] => int(1)
 	["b"] => int(2)
 	["c"] => int(3)
 	["d"] => int(4)
 	["e"] => int(5)
}

المثال 2: محاولة الوصول إلى خصائص غير صالحة للكائن

للوصول إلى عناصر الكائن التي تحتوي أحرف غير مسموح بها بموجب اتفاقيّة التّسمية في PHP (مثل الشرطة [hyphen]) فنضع اسم العنصر بين قوسين وبين علامتَي اقتباس.

<?php
$json = '{"foo-bar": 12345}';
$obj = json_decode($json);
print $obj->{'foo-bar'}; // 12345 
?>

المثال 3: أخطاء شائعة عند استخدام ()json_decode

<?php
// السّلاسل النصّيّة التّالية صالحة في جافاسكريبت وغير صالحة في JSON
 
// يجب وضع الاسم والقيمة بين علامتي تنصيص مزدوجتين
// علامات التّنصيص المفردة غير صالحة هنا
$bad_json = "{ 'bar': 'baz' }";
json_decode($bad_json); // null
 
// يجب وضع الاسم بين علامتي تنصيص مزدوجتين
$bad_json = '{ bar: "baz" }';
json_decode($bad_json); // null
 
// لا يسمح بوضع الفواصل الزّائدة
$bad_json = '{ bar: "baz", }';
json_decode($bad_json); // null
 
?>

المثال 4: أخطاء مُعامِل العُمق depth

<?php
// ترميز البيانات
 
$json = json_encode(
    array(
        1 => array(
            'English' => array(
                'One',
                'January'
            ),
            'French' => array(
                'Une',
                'Janvier'
            )
        )
    )
);
 
// تعريف الأخطاء
 
$constants = get_defined_constants(true);
$json_errors = array();
foreach ($constants["json"] as $name => $value) {
    if (!strncmp($name, "JSON_ERROR_", 11)) {
        $json_errors[$value] = $name;
    }
}
 
// إظهار الأخطاء بحسب اختلاف العمق
 
foreach (range(4, 3, -1) as $depth) {
    var_dump(json_decode($json, true, $depth));
    echo 'Last error: ', $json_errors[json_last_error()], PHP_EOL, PHP_EOL;
}
?>

ينتج عن المثال السّابق ما يلي:

array(1) {
  [1]=>
  array(2) {
        	["English"]=>
        	array(2) {
        	[0]=>
        	string(3) "One"
        	[1]=>
        	string(7) "January"
        	}
        	["French"]=>
        	array(2) {
        	[0]=>
        	string(3) "Une"
        	[1]=>
        	string(7) "Janvier"
        	}
  }
}
Last error: JSON_ERROR_NONE
 
NULL
Last error: JSON_ERROR_DEPTH

المثال 5: استخدام ()json_decode مع أعداد صحيحة كبيرة

<?php
$json = '{"number": 12345678901234567890}';
 
var_dump(json_decode($json));
var_dump(json_decode($json, false, 512, JSON_BIGINT_AS_STRING));
 
?>

ينتج عن المثال السّابق ما يلي:

object(stdClass)#1 (1) {
  ["number"]=>
  float(1.2345678901235E+19)
}
object(stdClass)#1 (1) {
  ["number"]=>
  string(20) "12345678901234567890"
}

ملاحظات

خصائص JSON هي ليست JavaScript وإنّما مجموعة فرعيّة من JavaScript.

تُستخدَم الدّالّة ()json_last_error لتحديد طبيعة الخطأ بالضّبط في حال فشل فك التّرميز.

سجل التغيرات

الإصدار	الوصف
7.1.0	يُرمَّز مفتاح JSON الفارغ ("") إلى خاصيّة كائن فارغة بدلًا من استخدام مفتاح مع القيمة _empty_.
7.0.0	رُفِضَت صيغ الأعداد غير المتوافقة مع المعيار RFC 7159، وهي المستويات العُليا من الأعداد (07، 0xff، .1، -.1) وكل مستويات الأعداد ([1.]، [1.e1]).
7.0.0	حدوث خطأ في صياغة JSON ناتج عن السّلسلة النصّيّة أو القيمة الفارغة في PHP والتي عند قلبها إلى سلسلة نصّيّة يكون الناتج سلسلة نصّيّة فارغة (NULL، أو FALSE).
5.6.0	لم تعد تُقبَل تنوعات أحرف القيم الثّابتة true و false و null المكتوبة بغير أحرف صغيرة كمُدخلات صالحة، وسيؤدّي استخدامها إلى تحذيرات.
5.4.0	أُضيف المُعامِل options.
5.3.0	أُضيف المُعامِل الاختياري depth، ورُفِعَت القيمة الافتراضيّة لعمق المُعاوَدة من 128 إلى 512.
5.2.3	رُفِعَت قيمة حدّ التداخل من 20 إلى 128.
5.2.1	أُضيف دعم فك ترميز JSON للأنواع الأساسيّة.

انظر أيضًا

• الدالة json_encode()‎: إعادة قيمة ما على شكل صيغة JSON.
• الدالة json_last_error()‎: إعادة آخر خطأ حاصل.

مصادر

• صفحة الدالة json_decode في توثيق PHP الرسمي.