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

(PHP 4, PHP 5, PHP 7)

تُولِّد الدالة serialize()‎‎‎‎‎‎‎‎‎‎‎‎‎‎‎ تمثيلًا قابلًا للتخزين لقيمة ما.

الوصف

string serialize ( mixed $value )

تُولِّد‎‎‎‎‎‎‎‎‎‎ تمثيلًا قابلًا للتخزين لقيمة ما.

يُفيد هذا في تخزين وتمرير قيم PHP بدون خسارة نوعها وبنيتها.

نستخدم الدالة unserialize()‎ لإرجاع السلسلة النصّيّة المتسلسلة إلى قيمة PHP مرّة أخرى.

المعاملات

value

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

تُحاوِل PHP عند سَلسَلة الكائنات أن تستدعي الدالة sleep()‎__ قبل إجراء السَّلسَلة ممّا يسمح للكائن «بتنظيف» أخير قبل سلسلته، وبالمثل عند استعادة الكائن باستخدام الدالة unserialize()‎ فستُستدعى الدالة العضو wakeup()‎__.

ملاحظة: تمتلك الأعضاء الخاصّة للكائن اسم الصّنف مُرفقًا مُسبقًا مع اسم العضو. تمتلك الأعضاء المحميّة القيمة '*' مُرفقةً مُسبقًا مع اسم العضو.

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

سلسلة نصّيّة تحتوي على تمثيل للمتغيّر ويُمكِن تخزينه في أي مكان.

لاحظ أنّها سلسلة نصّيّة بالنظام الثنائي وقد تتضمن بايتات null‏ (null bytes) وتحتاج إلى تخزينها والتعامل معها كذلك، فعلى سبيل المثال ينبغي بشكل عام تخزين خرج الدالة serialize()‎ في قاعدة البيانات في حقل BLOB بدلًا من حقل CHAR أو TEXT.

أمثلة

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

في المثال التالي يحتوي المتغيّر session_data‎$ على مصفوفة متعدّدة الأبعاد بمعلومات الجلسة للمستخدم الحالي. نستخدم الدالة serialize()‎ لتخزينها في قاعدة البيانات عند نهاية الطّلب:

<?php

$conn = odbc_connect("webdb", "php", "chicken");
$stmt = odbc_prepare($conn,
      "UPDATE sessions SET data = ? WHERE id = ?");
$sqldata = array (serialize($session_data), $_SERVER['PHP_AUTH_USER']);
if (!odbc_execute($stmt, $sqldata)) {
    $stmt = odbc_prepare($conn,
     "INSERT INTO sessions (id, data) VALUES(?, ?)");
    if (!odbc_execute($stmt, $sqldata)) {
        // حدث خطأ ما...
    }
}
?>

ملاحظات

لاحظ أنّ العديد من الكائنات المُضمَّنة في PHP لا يُمكِن سَلسَلتها، ولكن تعتمد الكائنات التي تملك القدرة على ذلك الواجهة Serializable أو التوابع sleep()‎__ و wakeup()‎__، إن لم يُحقِّق أحد الأصناف الداخلية أيٌ من هذه المتطلّبات فلا يُمكِن سَلسَلته.

توجد بعض الاستثناءات التاريخيّة لهذه القاعدة حيث يُمكِن سلسلة كائنات داخليّة بدون اعتماد هذه الواجهة أو استخدام تلك التوابع، مثل الكائن ArrayObject قبل الإصدار PHP 5.2.0.

تحذير: عندما تُسَلسِل الدالةُ serialize()‎ الكائنات، فلا تُضمَّن الشرطة المائلة الخلفية (backslash) في اسم الصّنف لتحقيق توافقيّة قصوى.

انظر أيضًا

• الدالة unserialize()‎: إنشاء قيمة PHP من تمثيل مُخزَّن.
• الدالة var_export()‎‎: إعادة أو إخراج تمثيل سلسلة نصّيّة قابل للتحليل.
• الدالة json_encode()‎: إعادة تمثيل بصيغة JSON لقيمة ما.
• سلسلة الكائنات Serializing Objects.
• الدالة sleep()‎__: تستدعى عند سَلسَلة الكائن.
• الدالة wakeup()‎__: تستدعى عند إنشاء قيمة PHP من تمثيل مُخزَّن.

مصادر

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