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

(PHP 4, PHP 5, PHP 7)

تُعطي الدالة unserialize()‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎ قيمة بلغة PHP انطلاقًا من تمثيل مُخزَّن.

الوصف

mixed unserialize ( string $str [, array $options ] )

تأخذ الدالة unserialize()‎ متغيّرًا متسلسلًا واحدًا وتُحوِّله مرّة أخرى إلى قيمة PHP.

تحذير: لا تُمرِّر مُدخَلات المستخدم غير الموثوقة إلى الدالة unserialize()‎ بغض النظر عن قيم المُعامِل options للأصناف المسموحة allowed_classes. قد ينتج عن فك التّسلسل تحميل وتنفيذ شيفرة ما وذلك نظرًا لاستنساخ الكائنات والتحميل التلقائي، ويُمكِن للمستخدم الضار استغلال ذلك. استخدم صيغة تبادل بيانات معياريّة وآمنة مثل JSON (عبر الدوال json_decode()‎ وjson_encode() ‎) إن احتجت إلى تمرير بيانات متسلسلة للمستخدم.

إن أردت فك تسلسل بيانات متسلسلة مُخزَّنة خارجيًّا، فانظر في استخدام الدالة hash_hmac()‎ من أجل التحقّق من البيانات، تأكّد من عدم تعديل البيانات من قبل أي شخص سواك.

المعاملات

str

السلسلة النصّيّة المتسلسلة.

إن كان المتغيّر المطلوب فك تسلسله عبارة عن كائن، فسيحاول بعد إعادة بنائه أن يستدعي الدالة العضو wakeup()‎‎__ (إن كانت موجودة).

ملاحظة: المُوجِّه unserialize_callback_func

من الممكن تعيين دالة استدعاء والتي تُستدعى عند استنساخ صنف غير مُعرَّف خلال فك التسلسل (لمنع الحصول على كائن غير مُكتمِل "PHP_Incomplete_Class__"). استخدم الملف php.ini، أو الدالة ini_set()‎ أو الملف htaccess‎. لتعريف unserialize_callback_func، ففي كل مرّة يُستنسَخ فيها صنف غير مُعرَّف ستُستدعى هذه الدالة، ولتعطيل هذه الميزة اجعل هذا الإعداد فارغًا فقط.

options

الخيارات التي يجب تزويدها لفك التسلسل كمصفوفة ترابطيّة.

الاسم	النوع	الوصف
allowed_classes	مختلط mixed	مصفوفة من أسماء الأصناف المقبولة، لرفض جميع الأصناف نضع القيمة FALSE، ولقبولها كلّها نضع القيمة TRUE. إن كان هذا الخيار مُعرَّفًا وصادفت الدالة unserialize()‎ كائنًا من صنف غير مسموح به، فسيتم استنساخ هذا الكائن من الصنف PHP_Incomplete_Class__ بدلًا من ذلك. إزالة هذا الخيار مماثلة لتعريف قيمته على أنّها TRUE، حيث ستحاول PHP استنساخ الكائنات لكافة الأصناف.

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

تُعاد القيمة المُحوَّلة، ويُمكِن أن تكون قيمةً منطقيّةً، أو عددًا صحيحًا، أو عددًا عشريًّا، أو سلسلةً نصّيّةً، أو مصفوفةً، أو كائنًا.

في حال كانت السّلسلة النصّيّة المُدخلَة غير قابلة لفك التسلسل تُعاد القيمة FALSE ويصدر الخطأ E_NOTICE.

سجل التغييرات

الإصدار	الوصف
7.1.0	أصبح العنصر allowed_classes من الخيارات صارمًا مع الكتابة، بمعنى أنّه عند إدخال أي شي عدا مصفوفة أو قيمة منطقيّة فستُعيد الدالة unserialize()‎ القيمة FALSE وستصدر التحذير E_WARNING.
7.0.0	أُضيف المُعامِل options.
5.6.0	فشل التلاعب بالبيانات المتسلسلة عبر استبدال C:‎ بالقيمة O:‎ لإجبار استنساخ الكائن بدون استدعاء الدالة البانية.

أمثلة

المثال 1: مثال على الدالة unserialize()‎

<?php

// unserialize()‎ نستخدم هنا الدالة
// $session_data لتحميل بيانات الجلسة إلى المصفوفة 
// من السلسلة المحددة من قاعدة البيانات

$conn = odbc_connect("webdb", "php", "chicken");
$stmt = odbc_prepare($conn, "SELECT data FROM sessions WHERE id = ?");
$sqldata = array($_SERVER['PHP_AUTH_USER']);
if (!odbc_execute($stmt, $sqldata) || !odbc_fetch_into($stmt, $tmp)) {
	// التهيئة إلى مصفوفة فارغة عند فشل التنفيذ أو جلب البيانات
    $session_data = array();
} else {
	// $tmp[0] ينبغي أن تكون لدينا الآن البيانات المتسلسلة في
    $session_data = unserialize($tmp[0]);
    if (!is_array($session_data)) {
		// حدث خطأ ما، التهيئة إلى مصفوفة فارغة
        $session_data = array();
    }
}
?>

المثال 2: مثال على unserialize_callback_func

<?php
$serialized_object='O:1:"a":1:{s:5:"value";s:3:"100";}';

ini_set('unserialize_callback_func', 'mycallback'); // تحديد تابع الاستدعاء

function mycallback($classname) 
{

	// فقط ضمّن ملفًا يحتوي على تعريف الصنف لديك
	// ستحصل على المتغيّر $classname لمعرفة أي تعريف للصنف هو المطلوب
}
?>

ملاحظات

تحذير: تُعاد القيمة FALSE في حال وجود خطأ أو عند فك تسلسل القيمة FALSE المتسلسلة، من الممكن الإمساك بهذه الحالة عبر مقارنة السلسلة النصّيّة str مع serialize(false)‎ أو عبر الإمساك بالخطأ الصادر E_NOTICE.

انظر أيضًا

• الدالة json_encode()‎: إعادة تمثيل بصيغة JSON لقيمة ما.
• الدالة json_decode()‎: فك ترميز سلسلة JSON.
• الدالة hash_hmac()‎: توليد قيمة تلبيد (hash) باستخدام التابع HMAC.
• الدالة serialize()‎: توليد تمثيل قابل للتخزين لقيمة ما.
• التحميل التلقائي للأصناف.
• الدالة var_export()‎‎: تُعيد أو تُخرِج تمثيل سلسلة نصّيّة قابل للتحليل.
• unserialize_callback_func.
• الدالة wakeup()‎__: تستدعى عند إنشاء قيمة PHP من تمثيل مُخزَّن.

مصادر

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