الفرق بين المراجعتين لصفحة: «PHP/session start»

المراجعة الحالية بتاريخ 08:01، 19 أغسطس 2018

(PHP 4, PHP 5, PHP 7)

تنشئ الدالة session_start()‎ جلسة جديدة أو تستكمل جلسة موجودة بالفعل.

الوصف

bool session_start ([ array $options = array() ])

تنشئ الدالة session_start()‎ جلسة جديدة أو تستكمل الجلسة الحالية بناء على مُعرف الجلسة المُمرر بواسطة الطلبية GET و POST أو عبر ملفات تعريف الارتباط.

عند استدعاء الدالة session_start()‎ أو عندما تبدأ الجلسة تلقائيًا، ستستدعي PHP دوال بدء وقراءة معلومات الجلسة. هذه الدوال ستكون إما دالة مضمَّنة في اللغة (built-in) ، أو بواسطة إضافات PHP (مِثل SQLite أو Memcached); أو يُمكن أن تكون مُخصصة مِثل دالة المعالجة المُعرَّفة بواسطة الدالة session_set_save_handler()‎. ستستعيد دالة رد النداء read أي بيانات موجودة للجلسة (المُخزنة بتنسيق مُتسلسل) وستقوم بفك ذلك التسلسل واستعمالها في المُتغير ‎$_SESSION.

لاستدعاء جلسة مُسماة، يجب أن تستدعي الدالة session_name()‎ قبل استدعاء الدالة session_start()‎.

عند تفعيل خيار الضبط session.use_trans_sid، ستسجل الدالة session_start()‎ مُعالِج مُخرجات داخلي لإعادة كتابة الروابط URL.

إذا كان المُستخدم يستعمل ob_gzhandler أو شبيهًا لها مِثل الدالة ob_start()‎، فإنّ ترتيب الدالة يصبح مُهما جدًا لإعادة المُخرجات بطريقة صحيحة.على سبيل المِثال، الدالة ob_gzhandler يجب أن تسجل قبل بداية الجلسة.

المعاملات

`options`

عند توفير هذا المعامل، ستحل مصفوفة من الاختيارات محل مسارات توثيق الجلسة الحالية. مفاتيح هذا المعامل يجب ألّا تحتوي على الحروف الأولية (prefix) للجلسة.

إضافةً إلى المجموعة العادية من خيارات الضبط، يمكن أيضًا توفير خيار الضبط read_and_close، وإذا ضُبِطَ إلى TRUE، فسيؤدي إلى إغلاق الجلسة مباشرةً بعد انتهاء قراءتها، مما يؤدي إلى تفادي قفل بيانات الجلسة إذا لم نكن ننوي تغييرها.

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

تُعيد الدالة القيمة TRUE في حالة نجاحها، أو القيمة FALSE فيما عدا ذلك.

أمثلة

مثال بسيط عن الجلسات

المثال 1: فتح جلسة أساسية لفتح الصفحة page1.php

<?php
// page1.php

session_start();

echo 'Welcome to page #1';

$_SESSION['favcolor'] = 'green';
$_SESSION['animal']   = 'cat';
$_SESSION['time']     = time();

// يعمل في حالة قبول ملفات تعريف الإرتباط للجلسة
echo '<br /><a href="page2.php">page 2</a>';

// أو يُمكن تمرير الرقم التعريفي للجلسة في حالة الحاجة لذلك
echo '<br /><a href="page2.php?' . SID . '">page 2</a>';

?>

بعد الإطلاع على الصفحة page1.php، سوف تحتوي الصفحة الثانية page2.php على بيانات الجلسة. المِثال 2: فتح جلسة أساسية لفتح الصفحة page2.php

<?php

// page2.php

session_start();
echo 'Welcome to page #2<br />';
echo $_SESSION['favcolor']; // green
echo $_SESSION['animal'];   // cat
echo date('Y m d H:i:s', $_SESSION['time']);

// يُمكن أن تستعمل معرف  للجلسة هُنا كما فعلنا في المِثال الأول

echo '<br /><a href="page1.php">page 1</a>';

?>

توفير المعامل `options` إلى الدالة `()session_start`.

المثال 3: تعديل فترة حياة ملفات الارتباط

<?php

// هذا يُرسل  ملفات ارتباط تستمر لأسبوع
session_start([
    'cookie_lifetime' => 86400,
]);
?>

المثال 4: قراءة الجلسة وإغلاقها

<?php
/*
 إذا كنا نعلم أننا لا نحتاج إلى تغيير أي شيء في الجلسة ، فيمكننا فقط القراءة والإغلاق على الفور لتجنب قفل ملف الجلسة ومنع صفحات أخرى
*/
session_start([
    'cookie_lifetime' => 86400,
    'read_and_close'  => true,
]);

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

الإصدار	الوصف
7.1.0	تعيد الدالة القيمة `FALSE` ولا تعطي قيمة أولية للمُتغير ‎`$_SESSION` عند فشل بدء الجلسة.
7.0.0	أضيف المعامل `options`.
5.3.0	عند فشل الدالة سوف تُعيد القيمة `FALSE`، قبل ذلك كانت تُعيد `TRUE`.
4.3.3	في ذلك الإصدار وما قبل، إذا استدعيت الدالة بعد بدء الجلسة، سيظهر خطأ من نوع `E_NOTICE`، وستُهمل الدالة الثانية لبدء الجلسة.

ملاحظات

لاحظ أنه لغرض استعمالك للجلسات المبنية على ملفات تعريف الارتباط، فإن الدالة session_start()‎ يجب أن تُستدعى قبل إخراج أي شيء للمتصفح.

يُنصح باستخدام zlib.output_compression بدلًا مِن ob_gzhandler()‎.

تُرسل الدالة session_start()‎ العديد من الملفات الترويسية (HTTP header files) اعتمادًا على الضبط المستخدم. راجع شرح الدالة session_cache_limiter()‎ لتخصيص هذه الملفات.

انظر أيضًا

الدالة session_id()‎: تحصل على أو تضبط المعرف الخاص بالجلسة.

مصادر

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

@@ سطر 1: / سطر 1: @@
-<noinclude>{{DISPLAYTITLE:الدالة session_start()‎ في PHP
+<noinclude>{{DISPLAYTITLE:الدالة <code>session_start()</code>‎ في PHP}}</noinclude>
-}}</noinclude>
+(PHP 4, PHP 5, PHP 7)
+تنشئ  الدالة <code>session_start()</code>‎ جلسة جديدة أو تستكمل جلسة موجودة بالفعل.
+== الوصف ==
+<syntaxhighlight lang="php">
+bool session_start ([ array $options = array() ])
+</syntaxhighlight>تنشئ الدالة <code>session_start()‎</code> جلسة جديدة أو تستكمل الجلسة الحالية بناء على مُعرف الجلسة المُمرر بواسطة الطلبية GET و POST أو عبر ملفات تعريف الارتباط.
+عند استدعاء الدالة <code>session_start()</code>‎ أو عندما تبدأ الجلسة تلقائيًا، ستستدعي  PHP دوال بدء وقراءة معلومات الجلسة. هذه الدوال ستكون إما دالة مضمَّنة في اللغة (built-in) ، أو بواسطة إضافات PHP (مِثل SQLite أو Memcached); أو يُمكن أن تكون مُخصصة مِثل دالة المعالجة المُعرَّفة بواسطة الدالة <code>[[PHP/session set save handler|session_set_save_handler()]]</code>‎. ستستعيد دالة رد النداء <code>read</code> أي بيانات موجودة للجلسة (المُخزنة بتنسيق مُتسلسل) وستقوم بفك ذلك التسلسل واستعمالها في المُتغير ‎<code>$_SESSION</code>.
+ لاستدعاء جلسة مُسماة، يجب أن تستدعي الدالة <code>[[PHP/session name|session_name()‎]]</code> قبل استدعاء الدالة <code>session_start()‎</code>.
+ عند تفعيل خيار الضبط <code>session.use_trans_sid</code>، ستسجل الدالة <code>session_start()‎</code> مُعالِج مُخرجات داخلي لإعادة كتابة الروابط URL.
+ إذا كان المُستخدم يستعمل <code>ob_gzhandler</code> أو شبيهًا لها مِثل الدالة <code>[[PHP/ob start|ob_start()]]</code>‎، فإنّ ترتيب الدالة يصبح مُهما جدًا لإعادة المُخرجات بطريقة صحيحة.على سبيل المِثال، الدالة <code>ob_gzhandler</code> يجب أن تسجل قبل بداية الجلسة.
+== المعاملات ==
+=== <code>options</code> ===
+عند توفير هذا المعامل، ستحل مصفوفة من الاختيارات محل مسارات توثيق الجلسة الحالية. مفاتيح هذا المعامل يجب ألّا تحتوي على الحروف الأولية (prefix) للجلسة.
+إضافةً إلى المجموعة العادية من خيارات الضبط، يمكن أيضًا توفير خيار الضبط <code>read_and_close</code>، وإذا ضُبِطَ إلى <code>TRUE</code>، فسيؤدي إلى إغلاق الجلسة مباشرةً بعد انتهاء قراءتها، مما يؤدي إلى تفادي قفل بيانات الجلسة إذا لم نكن ننوي تغييرها.
+== القيم المعادة ==
+تُعيد الدالة القيمة <code>TRUE</code> في حالة نجاحها، أو القيمة <code>FALSE</code> فيما عدا ذلك.
+== أمثلة ==
+=== مثال بسيط عن الجلسات ===
+المثال 1: فتح جلسة أساسية لفتح الصفحة page1.php<syntaxhighlight lang="php">
+<?php
+// page1.php
+session_start();
+echo 'Welcome to page #1';
+$_SESSION['favcolor'] = 'green';
+$_SESSION['animal']   = 'cat';
+$_SESSION['time']     = time();
+// يعمل في حالة قبول ملفات تعريف الإرتباط للجلسة
+echo '<br /><a href="page2.php">page 2</a>';
+// أو يُمكن تمرير الرقم التعريفي للجلسة في حالة الحاجة لذلك
+echo '<br /><a href="page2.php?' . SID . '">page 2</a>';
+?>
+</syntaxhighlight>بعد الإطلاع على الصفحة page1.php، سوف تحتوي الصفحة الثانية page2.php  على بيانات الجلسة.
+المِثال 2: فتح جلسة أساسية لفتح الصفحة page2.php<syntaxhighlight lang="php">
+<?php
+// page2.php
+session_start();
+echo 'Welcome to page #2<br />';
+echo $_SESSION['favcolor']; // green
+echo $_SESSION['animal'];   // cat
+echo date('Y m d H:i:s', $_SESSION['time']);
+// يُمكن أن تستعمل معرف  للجلسة هُنا كما فعلنا في المِثال الأول
+echo '<br /><a href="page1.php">page 1</a>';
+?>
+</syntaxhighlight>
+=== توفير المعامل <code>options</code> إلى الدالة <code>()session_start</code>. ===
+المثال 3: تعديل فترة حياة ملفات الارتباط <syntaxhighlight lang="php">
+<?php
+// هذا يُرسل  ملفات ارتباط تستمر لأسبوع
+session_start([
+    'cookie_lifetime' => 86400,
+]);
+?>
+</syntaxhighlight>المثال 4: قراءة الجلسة وإغلاقها<syntaxhighlight lang="php">
+<?php
+/*
+ إذا كنا نعلم أننا لا نحتاج إلى تغيير أي شيء في الجلسة ، فيمكننا فقط القراءة والإغلاق على الفور لتجنب قفل ملف الجلسة ومنع صفحات أخرى
+*/
+session_start([
+    'cookie_lifetime' => 86400,
+    'read_and_close'  => true,
+]);
+</syntaxhighlight>
+== سجل التغييرات ==
+{| class="wikitable"
+!الإصدار
+!الوصف
+|-
+|7.1.0
+|تعيد الدالة القيمة <code>FALSE</code> ولا تعطي قيمة أولية للمُتغير ‎<code>$_SESSION</code> عند فشل بدء الجلسة.
+|-
+|7.0.0
+|أضيف المعامل <code>options</code>.
+|-
+|5.3.0
+|عند فشل الدالة سوف تُعيد القيمة <code>FALSE</code>، قبل ذلك كانت تُعيد <code>TRUE</code>.
+|-
+|4.3.3
+|في ذلك الإصدار وما قبل، إذا استدعيت الدالة بعد بدء الجلسة، سيظهر خطأ من نوع  <code>E_NOTICE</code>، وستُهمل الدالة الثانية لبدء الجلسة.
+|}
+== ملاحظات ==
+لاحظ أنه لغرض استعمالك للجلسات المبنية على ملفات تعريف الارتباط، فإن الدالة <code>session_start()</code>‎ يجب أن تُستدعى قبل إخراج أي شيء للمتصفح.
+يُنصح باستخدام <code>zlib.output_compression</code> بدلًا مِن <code>ob_gzhandler()‎</code>.
+تُرسل الدالة <code>session_start()‎</code> العديد من الملفات الترويسية (HTTP header files) اعتمادًا على الضبط المستخدم. راجع شرح الدالة <code>[[PHP/session cache limiter|session_cache_limiter()]]</code>‎ لتخصيص هذه الملفات.
+== انظر أيضًا ==
+* الدالة <code>[[PHP/session id|session_id()]]</code>‎: تحصل على أو تضبط المعرف الخاص بالجلسة.
+== مصادر ==
+* [http://php.net/manual/en/function.session-start.php صفحة الدالة session_start في توثيق PHP الرسمي.]
+[[تصنيف:PHP]]
+[[تصنيف:PHP Function]]
+[[تصنيف:PHP Session]]