عرض مصدر PHP/unserialize

<noinclude>{{DISPLAYTITLE:الدالة <code>unserialize()</code>‎ في PHP}}</noinclude>
(PHP 4, PHP 5, PHP 7)

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

== الوصف ==
<syntaxhighlight lang="php">
mixed unserialize ( string $str [, array $options ] )

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

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

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

== المعاملات ==

=== <code>str</code> ===
السلسلة النصّيّة المتسلسلة.

إن كان المتغيّر المطلوب فك تسلسله عبارة عن كائن، فسيحاول بعد إعادة بنائه أن يستدعي الدالة العضو <code>[[PHP/magic#.E2.80.8E sleep.28.29.E2.80.8E .D9.88 .E2.80.8E wakeup.28.29.E2.80.8E|wakeup()‎‎__]]</code> (إن كانت موجودة).

ملاحظة: المُوجِّه <code>unserialize_callback_func</code>

من الممكن تعيين دالة استدعاء والتي تُستدعى عند استنساخ صنف غير مُعرَّف خلال فك التسلسل (لمنع الحصول على [[PHP/object|كائن]] غير مُكتمِل "<code>PHP_Incomplete_Class__</code>"). استخدم الملف <code>php.ini</code>، أو الدالة <code>[[PHP/ini set|ini_set()]]</code>‎ أو الملف <code>htaccess‎.</code> لتعريف <code>[http://php.net/manual/en/var.configuration.php#ini.unserialize-callback-func unserialize_callback_func]</code>، ففي كل مرّة يُستنسَخ فيها صنف غير مُعرَّف ستُستدعى هذه الدالة، ولتعطيل هذه الميزة اجعل هذا الإعداد فارغًا فقط.

=== <code>options</code> ===
الخيارات التي يجب تزويدها لفك التسلسل كمصفوفة ترابطيّة.

{| class="wikitable"
!الاسم
!النوع
!الوصف
|-
|allowed_classes
|[[PHP/pseudo types#.D9.85.D8.AE.D8.AA.D9.84.D8.B7 .E2.80.93 mixed|مختلط mixed]]
|مصفوفة من أسماء الأصناف المقبولة، لرفض جميع الأصناف نضع القيمة <code>FALSE</code>، ولقبولها كلّها نضع القيمة <code>TRUE</code>. إن كان هذا الخيار مُعرَّفًا وصادفت الدالة <code>unserialize()</code>‎ كائنًا من صنف غير مسموح به، فسيتم استنساخ هذا الكائن من الصنف <code>PHP_Incomplete_Class__</code> بدلًا من ذلك. إزالة هذا الخيار مماثلة لتعريف قيمته على أنّها <code>TRUE</code>، حيث ستحاول PHP استنساخ الكائنات لكافة الأصناف.
|}

== القيم المعادة ==
تُعاد القيمة المُحوَّلة، ويُمكِن أن تكون [[PHP/boolean|قيمةً منطقيّةً]]، أو [[PHP/integer|عددًا صحيحًا]]، أو [[PHP/float|عددًا عشريًّا]]، أو [[PHP/string|سلسلةً نصّيّةً]]، أو [[PHP/array|مصفوفةً]]، أو [[PHP/object|كائنًا]].

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

== سجل التغييرات ==
{| class="wikitable"
!الإصدار
!الوصف
|-
|7.1.0
|أصبح العنصر <code>allowed_classes</code> من الخيارات صارمًا مع الكتابة، بمعنى أنّه عند إدخال أي شي عدا مصفوفة أو قيمة منطقيّة فستُعيد الدالة <code>unserialize()‎</code> القيمة <code>FALSE</code> وستصدر التحذير <code>E_WARNING</code>.
|-
|7.0.0
|أُضيف المُعامِل <code>options</code>.
|-
|5.6.0
|فشل التلاعب بالبيانات المتسلسلة عبر استبدال <code>C:‎</code> بالقيمة <code>O:</code>‎ لإجبار استنساخ الكائن بدون استدعاء الدالة البانية.
|}

== أمثلة ==
المثال 1: مثال على الدالة <code>unserialize()</code>‎<syntaxhighlight lang="php">
<?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();
    }
}
?>

</syntaxhighlight>المثال 2: مثال على <code>unserialize_callback_func</code><syntaxhighlight lang="php">
<?php
$serialized_object='O:1:"a":1:{s:5:"value";s:3:"100";}';

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

function mycallback($classname) 
{

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

</syntaxhighlight>

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

== انظر أيضًا ==
* الدالة <code>[[PHP/json encode|json_encode()]]</code>‎: إعادة تمثيل بصيغة JSON لقيمة ما.
* الدالة <code>[[PHP/json decode|json_decode()]]</code>‎: فك ترميز سلسلة JSON.
* الدالة <code>[[PHP/hash hmac|hash_hmac()]]</code>‎: توليد قيمة تلبيد (hash) باستخدام التابع HMAC.
* الدالة <code>[[PHP/serialize|serialize()‎]]</code>: توليد تمثيل قابل للتخزين لقيمة ما.
* [[PHP/autoload|التحميل التلقائي للأصناف]].
* الدالة <code>[[PHP/var export|var_export()‎]]</code>‎: تُعيد أو تُخرِج تمثيل سلسلة نصّيّة قابل للتحليل.
* [http://php.net/manual/en/var.configuration.php#ini.unserialize-callback-func unserialize_callback_func].
* الدالة <code>[[PHP/magic#.E2.80.8E sleep.28.29.E2.80.8E .D9.88 .E2.80.8E wakeup.28.29.E2.80.8E|wakeup()‎__]]</code>: تستدعى عند إنشاء قيمة PHP من تمثيل مُخزَّن.

== مصادر ==
* [http://php.net/manual/en/function.unserialize.php صفحة الدالة unserialize في توثيق PHP الرسمي].
[[تصنيف:PHP]]
[[تصنيف:PHP Function]]
[[تصنيف:PHP Variable Handling]]