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

(PHP 4 >= 4.3.2, PHP 5, PHP 7)

تُحدث الدالة session_regenerate_id()‎ معرف الجلسة الحالية عن طريق توليد معرف جديد.

الوصف

bool session_regenerate_id ([ bool $delete_old_session = FALSE ] )

تبدل الدالة session_regenerate_id()‎ معرف الجلسة  الحالية برقم جديد وتُبقي على باقي معلومات الجلسة الحالية.

عند تفعيل session.use_trans_sid، يجب أن يبدأ الإخراج بعد استدعاء الدالة()session_regenerate_id، والا سيُستعمل معرف الجلسة القديم.

المعاملات

delete_old_session

سواء قمت بحذف ملف الجلسة المرتبطة أم لا، يجب ألّا تمسح الجلسة القديمة إذا أردت تجنب أو كشف هجمات سرقة الجلسات.

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

تُعيد الدالة session_regenerate_id()‎ القيمة TRUE في حالة نجاحها، وإلاّ فستُعيد القيمة FALSE.

أمثلة

المثال 1: مثال عن استعمال الدالة session_regenerate_id()‎

<?php

// هذا المثال لا يعمل، إنما لتوضيح كتابة الدالة

session_start();

// المُدمرtime-stamp تحقق مِن
if (isset($_SESSION['destroyed'])
    && $_SESSION['destroyed'] < time() - 300) {
    // لا يحدث عادةً إلا في حالة هجوم أو شبكة غير مُستقرة
    // يمسح حالة جلسة هذا المُستخدم
    remove_all_authentication_flag_from_active_sessions($_SESSION['userid']);
    throw(new DestroyedSessionAccessException);
}

$old_sessionid = session_id();

// ضبط الفترة الزمنية لتدمير الجلسة
$_SESSION['destroyed'] = time(); 

// الدالة تقوم بحفظ بيانات الجلسة القديمة PHP 7.0.0 منذ إصدار
// شاهد المثال التالي
session_regenerate_id();

// destroyed timestamp الدالة الجديدة لا تحتاج مُتغير التدمير
unset($_SESSION['destroyed']);

$new_sessionid = session_id();

echo "Old Session: $old_sessionid<br />";
echo "New Session: $new_sessionid<br />";

print_r($_SESSION);

?>

الوحدة البرمجية المستخدمة للجلسة لا تسمح بالتعامل مع الشبكات غير المُستقرة، مِثل الهاتف المحمول و Wifi. لذا يجب إدارة معرف الجلسة عن طريق الدالة session_regenerate_id()‎ لتجنب فقدان الجلسة. المثال 2: تجنب فقدان الجلسة عن طريق استعمال session_regenerate_id()‎

<?php

/*

!هذا كود توضيحي ولا يعمل
دالة البداية ودالة توليد المعرف  تتجنبان فقدان الجلسات بواسطة الشبكات الغير مُستقرة بالإضافة إلى منع هجمات سرقة الجلسات

*/

function my_session_start() {
    session_start();
    if (isset($_SESSION['destroyed'])) {
       if ($_SESSION['destroyed'] < time()-300) {
           // لا يحدث عادةً إلا في حالة هجوم أو شبكة غير مُستقرة
           // يمسح حالة جلسة هذا المُستخدم
           remove_all_authentication_flag_from_active_sessions($_SESSION['userid']);
           throw(new DestroyedSessionAccessException);
       }
       if (isset($_SESSION['new_session_id'])) {
           session_commit();
           session_id($_SESSION['new_session_id']);
           // يجب أن يظهر معرف  جديد للجلسة
           session_start();
           return;
       }
   }
}

function my_session_regenerate_id() {
    // يتطلب تحديد معرف  جديد مُناسب
    // عند إلغاء ضبطه بسبب عدم استقرار الشبكة
    $new_session_id = session_create_id();
    $_SESSION['new_session_id'] = $new_session_id; 

    // destroy timestamp ضبط
    $_SESSION['destroyed'] = time();    

    // كتابة و إنهاء الجلسة الحالية
    session_commit();

    // إبدأ الجلسة بالمعرف  الجديد
    session_id($new_session_id);
    ini_set('session.use_strict_mode', 0);
    session_start();
    ini_set('session.use_strict_mode', 1);
    
    // الدالة لا تحتاج هذه المُتغيرات
    unset($_SESSION['destroyed']);
    unset($_SESSION['new_session_id']);
}
?>

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

الإصدار	الوصف
7.0.0	تحفظ الدالة session_regenerate_id()‎ بيانات الجلسة القديمة قبل إغلاقها.
5.1.0	أُضيف المُعامل delete_old_session.
4.3.3	في ذلك الإصدار وما قبل، إذا فعلت ملفات تعريف الارتباط (كوكيز) الخاصة بالجلسة، فإن استعمال الدالة session_regenerate_id()‎ سينجرّ عنه إنشاء ملف ارتباط جديد و معرف جديد.

انظر أيضًا

• الدالة session_is_registered()‎: تتحقق من وجود (أو تسجيل) المتغير العام المُمرَّر إليها في الجلسة.
• الدالة ()session_unregister: تقوم بفك تسجيل المتغير العام المُمرَّر إليها في الجلسة.

مصادر

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