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

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

تُعيد الدالة json_encode()‎ قيمةً ما على شكل صيغة JSON.

الوصف

string json_encode ( mixed $value [, int $options = 0 [, int $depth = 512 ]] )

تُعيد سلسلة نصّيّة على شكل صيغة JSON للقيمة المُدخلة.

يتأثّر الترميز بالخيارات المُعطاة للمُعامِل options ويعتمد ترميز القيم من نوع عدد ذو فاصلة عائمة (float) على القيمة المُحدَّدة في الإعدادات للخيار serialize_precision.

المعاملات

value

وهي القيمة المطلوب ترميزها، يمكن أن تكون من أي نوع عدا الموارد (resource).

يجب ترميز جميع بيانات السّلاسل النصّيّة بصيغة UTF-8.

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

options

خيارات على شكل قناع بت Bitmask، وهي JSON_HEX_QUOT و JSON_HEX_TAG و JSON_HEX_AMP و JSON_HEX_APOS و JSON_NUMERIC_CHECK و JSON_PRETTY_PRINT و JSON_UNESCAPED_SLASHES و JSON_FORCE_OBJECT و JSON_PRESERVE_ZERO_FRACTION و JSON_UNESCAPED_UNICODE و JSON_PARTIAL_OUTPUT_ON_ERROR. يُوجد وصف لسلوك كل من هذه الثّوابت على الصّفحة ثوابت JSON.

depth

يُحدِّد العمق الأقصى، ويجب أن يكون أكبر من الصّفر.

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

تُعيد هذه الدّالّة سلسلة نصّيّة مُرمَّزة بصيغة JSON عند النّجاح، أو القيمة FALSE عند الفشل.

سجل التغيرات

الإصدار	الوصف
7.1.0	استُخدِم الخيار serialize_precision بدلًا من الخيار precision عند ترميز القيم من نوع double.
5.6.6	أُضيف الخيار JSON_PRESERVE_ZERO_FRACTION.
5.5.0	أُضيف مُعامِل العمق depth.
5.5.0	أُضيف الخيار JSON_PARTIAL_OUTPUT_ON_ERROR.
5.5.0	تغيّرت القيمة المُعادة عند الفشل من null إلى FALSE.
5.4.0	أُضيفت الخيارات JSON_PRETTY_PRINT، و JSON_UNESCAPED_SLASHES، و JSON_UNESCAPED_UNICODE.
5.3.3	أُضيف الخيار JSON_NUMERIC_CHECK.
5.3.0	أُضيف المُعامِل options.

أمثلة

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

<?php
$arr = array('a' => 1, 'b' => 2, 'c' => 3, 'd' => 4, 'e' => 5);
 
echo json_encode($arr);
?>

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

{"a":1,"b":2,"c":3,"d":4,"e":5}

المثال 2: مثال على الدالة json_encode()‎ يُظهِر استعمال بعض الخيارات معها

<?php
$a = array('<foo>',"'bar'",'"baz"','&blong&', "\xc3\xa9");
 
echo "Normal: ",  json_encode($a), "\n";
echo "Tags: ",    json_encode($a, JSON_HEX_TAG), "\n";
echo "Apos: ",    json_encode($a, JSON_HEX_APOS), "\n";
echo "Quot: ",    json_encode($a, JSON_HEX_QUOT), "\n";
echo "Amp: ",     json_encode($a, JSON_HEX_AMP), "\n";
echo "Unicode: ", json_encode($a, JSON_UNESCAPED_UNICODE), "\n";
echo "All: ",     json_encode($a, JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_HEX_AMP | JSON_UNESCAPED_UNICODE), "\n\n";
 
$b = array();
 
echo "Empty array output as array: ", json_encode($b), "\n";
echo "Empty array output as object: ", json_encode($b, JSON_FORCE_OBJECT), "\n\n";
 
$c = array(array(1,2,3));
 
echo "Non-associative array output as array: ", json_encode($c), "\n";
echo "Non-associative array output as object: ", json_encode($c, JSON_FORCE_OBJECT), "\n\n";
 
$d = array('foo' => 'bar', 'baz' => 'long');
 
echo "Associative array always output as object: ", json_encode($d), "\n";
echo "Associative array always output as object: ", json_encode($d, JSON_FORCE_OBJECT), "\n\n";
?>

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

Normal: ["<foo>","'bar'","\"baz\"","&blong&","\u00e9"]
Tags: ["\u003Cfoo\u003E","'bar'","\"baz\"","&blong&","\u00e9"]
Apos: ["<foo>","\u0027bar\u0027","\"baz\"","&blong&","\u00e9"]
Quot: ["<foo>","'bar'","\u0022baz\u0022","&blong&","\u00e9"]
Amp: ["<foo>","'bar'","\"baz\"","\u0026blong\u0026","\u00e9"]
Unicode: ["<foo>","'bar'","\"baz\"","&blong&","é"]
All: ["\u003Cfoo\u003E","\u0027bar\u0027","\u0022baz\u0022","\u0026blong\u0026","é"]
 
Empty array output as array: []
Empty array output as object: {}
 
Non-associative array output as array: [[1,2,3]]
Non-associative array output as object: {"0":{"0":1,"1":2,"2":3}}
 
Associative array always output as object: {"foo":"bar","baz":"long"}
Associative array always output as object: {"foo":"bar","baz":"long"}

المثال 3: مثال عن الخيار JSON_NUMERIC_CHECK

<?php
echo "Strings representing numbers automatically turned into numbers".PHP_EOL;
$numbers = array('+123123', '-123123', '1.2e3', '0.00001');
var_dump(
 $numbers,
 json_encode($numbers, JSON_NUMERIC_CHECK)
);
echo "Strings containing improperly formatted numbers".PHP_EOL;
$strings = array('+a33123456789', 'a123');
var_dump(
 $strings,
 json_encode($strings, JSON_NUMERIC_CHECK)
);
?>

ينتج عن المثال السّابق خَرْج مشابه للتالي:

Strings representing numbers automatically turned into numbers
array(4) {
  [0]=>
  string(7) "+123123"
  [1]=>
  string(7) "-123123"
  [2]=>
  string(5) "1.2e3"
  [3]=>
  string(7) "0.00001"
}
string(28) "[123123,-123123,1200,1.0e-5]"
Strings containing improperly formatted numbers
array(2) {
  [0]=>
  string(13) "+a33123456789"
  [1]=>
  string(4) "a123"
}
string(24) "["+a33123456789","a123"]"

المثال 4: مثال يوضّح الفرق بين المصفوفات المتسلسلة والمصفوفات غير المتسلسلة

<?php
echo "Sequential array".PHP_EOL;
$sequential = array("foo", "bar", "baz", "blong");
var_dump(
 $sequential,
 json_encode($sequential)
);
 
echo PHP_EOL."Non-sequential array".PHP_EOL;
$nonsequential = array(1=>"foo", 2=>"bar", 3=>"baz", 4=>"blong");
var_dump(
 $nonsequential,
 json_encode($nonsequential)
);
 
echo PHP_EOL."Sequential array with one key unset".PHP_EOL;
unset($sequential[1]);
var_dump(
 $sequential,
 json_encode($sequential)
);
?>

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

Sequential array
array(4) {
  [0]=>
  string(3) "foo"
  [1]=>
  string(3) "bar"
  [2]=>
  string(3) "baz"
  [3]=>
  string(5) "blong"
}
string(27) "["foo","bar","baz","blong"]"
 
Non-sequential array
array(4) {
  [1]=>
  string(3) "foo"
  [2]=>
  string(3) "bar"
  [3]=>
  string(3) "baz"
  [4]=>
  string(5) "blong"
}
string(43) "{"1":"foo","2":"bar","3":"baz","4":"blong"}"
 
Sequential array with one key unset
array(3) {
  [0]=>
  string(3) "foo"
  [2]=>
  string(3) "baz"
  [3]=>
  string(5) "blong"
}
string(33) "{"0":"foo","2":"baz","3":"blong"}"

المثال 5: مثال عن الخيار JSON_PRESERVE_ZERO_FRACTION

<?php
var_dump(json_encode(12.0, JSON_PRESERVE_ZERO_FRACTION));
var_dump(json_encode(12.0));
?>

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

string(4) "12.0"
string(2) "12"

ملاحظات

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

إن لم تكن المفاتيح عند ترميز المصفوفة ذات تسلسل عددي مُتتابِع بدءًا من الصّفر فستُرمَّز جميع هذه المفاتيح كسلاسل نصّيّة وتُحدَّد بشكل خاص لكل زوج مفتاح-قيمة (key-value).

تُعطينا الدّالّة json_encode()‎ صيغة JSON كقيمة بسيطة (أي ليست على شكل كائن أو مصفوفة) وذلك عند إدخال سلسلة نصّيّة، أو عدد صحيح، أو عدد ذو فاصلة عائمة، أو قيمة منطقيّة (boolean). ومع أنّ أغلب أدوات فك التّرميز تقبل هذه القيم كصيغة JSON صالحة، فقد تواجه بعضًا منها التي لن تقبل ذلك، حيث أنّ مواصفة JSON غير واضحة حول هذه النّقطة.

ولتلخيص ذلك تأكّد من قدرة أداة فك ترميز JSON لديك على التّعامل مع ناتج الدّالّةjson_encode()‎.

انظر أيضًا

• الصنف JsonSerializable.
• الدالة json_decode()‎: فك ترميز سلسلة JSON.
• الدالة json_last_error()‎: إعادة آخر خطأ حاصل.
• الدالة serialize()‎: إنتاج تمثيل قابل للتخزين لقيمة ما.

مصادر

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