عرض مصدر PHP/session regenerate id

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

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

== الوصف ==
<syntaxhighlight lang="php">
bool session_regenerate_id ([ bool $delete_old_session = FALSE ] )
</syntaxhighlight>تبدل الدالة <code>session_regenerate_id()</code>‎ معرف الجلسة  الحالية برقم جديد وتُبقي على باقي معلومات الجلسة الحالية.

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

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

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

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

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

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

المثال 2: تجنب فقدان الجلسة عن طريق استعمال <code>session_regenerate_id()</code>‎<syntaxhighlight lang="php">
<?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']);
}
?>

</syntaxhighlight>

== سجل التغييرات ==
{| class="wikitable"
!الإصدار
!الوصف
|-
|7.0.0
|تحفظ الدالة <code>session_regenerate_id()‎</code> بيانات الجلسة القديمة قبل إغلاقها.
|-
|5.1.0
|أُضيف المُعامل <code>delete_old_session</code>.
|-
|4.3.3
|في ذلك الإصدار وما قبل، إذا فعلت ملفات تعريف الارتباط (كوكيز) الخاصة بالجلسة، فإن استعمال الدالة <code>session_regenerate_id()</code>‎ سينجرّ عنه إنشاء ملف ارتباط جديد و معرف جديد.
|}

== انظر أيضًا ==
* الدالة <code>[[PHP/session is registered|session_is_registered()]]</code>‎: تتحقق من وجود (أو تسجيل) المتغير العام المُمرَّر إليها في الجلسة.
* الدالة <code>[[PHP/session unregister|()session_unregister]]</code>: تقوم بفك تسجيل المتغير العام المُمرَّر إليها في الجلسة.

== مصادر ==
* [http://php.net/manual/en/function.session-regenerate-id.php صفحة الدالة session_regenrate_id في توثيق PHP الرسمي.]
[[تصنيف:PHP]]
[[تصنيف:PHP Function]]
[[تصنيف:PHP Session]]