الفرق بين المراجعتين ل"PHP/unserialize"

من موسوعة حسوب
< PHP
اذهب إلى التنقل اذهب إلى البحث
(أنشأ الصفحة ب'<noinclude>{{DISPLAYTITLE:الدالة <code>unserialize()</code>‎ في PHP}}</noinclude>')
 
(تعديل رابط صفحة التحميل التلقائي)
 
(مراجعة متوسطة واحدة بواسطة مستخدم واحد آخر غير معروضة)
سطر 1: سطر 1:
 
<noinclude>{{DISPLAYTITLE:الدالة <code>unserialize()</code>‎ في PHP}}</noinclude>
 
<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/autoloading|التحميل التلقائي للأصناف]].
 +
* الدالة <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]]

المراجعة الحالية بتاريخ 14:30، 6 يونيو 2018

(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.

انظر أيضًا

مصادر

مجلوبة من "https://wiki.hsoub.com/index.php?title=PHP/unserialize&oldid=10169"