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

(PHP 4, PHP 5, PHP 7)

تفتح الدالة fopen()‎ ملفًا أو عنوان URL.

الوصف

resource fopen ( string $filename , string $mode [, bool$use_include_path = FALSE [, resource $context ]] )

تربط هذه الدالة المورد filename المحدَّد مع مجرى (stream).

المعاملات

filename

إن كانت قيمة هذا المعامل بالشكل "scheme://..‎"، فستعاملها PHP على أنَّها عنوان URL وستبحث حينئذٍ على معالج البروتوكول (portocol handler) من أجل ذلك المخطَّط (scheme). إن لم يكن هنالك بروتوكول مُسجَّل، فستُصدر PHP ملاحظةً لتساعدك على تعقُّب المشكلة المحتملة في سكربتك ثمَّ تكمل بعدئذٍ بتحديد قيمة المعامل filename على أنَّها ملف طبيعي.

إن قرَّرت PHP أنَّ المعامل filename هو ملف محلي، فستحاول فتح مجرى لهذا الملف. يجب أن تستطيع PHP الوصول إلى ذلك الملف، لذا تأكَّد من أنَّ أذونات الوصول للملف تسمح بذلك. إن كان الوضع الآمن (safe mode) أو الوضع open_basedir مُفعَّلًا، فقد تُطبَّق قيود إضافيَّة.

إن قرَّرت PHP أنَّ المعامل filename هو بروتوكول مسجَّل وكان هذا البروتوكول مُسجَّلًا على أنَّه عنوان URL شبكي، فستتأكد حينئذٍ من تفعيل الخيار allow_url_fopen. إن لم يكن ذلك الخيار مُفعَّلًا، فتصدر PHP تحذيرًا وسيفشل استدعاء الدالة fopen()‎.

ملاحظة: قائمة البروتوكولات المدعومة تجدها في صفحة البروتوكولات المدعومة. تدعم بعض البروتوكولات المحتوى (context) وخيارات php.ini أو بعضها. ارجع إلى الصفحة المخصَّصة للبروتوكول المُستعمل لمعرفة قائمة الخيارات التي يمكن ضبطها (مثل القيمة user_agent في php.ini التي يستعملها البروتوكول http).

لا تنسَ استعمال محرف التهريب (الخط المائل العكسي) لتهريب الخط المائل العكسي المستعمل ضمن المسار في ويندوز. يمكنك الاستعاضة عن ذلك باستعمال الخط المائل الأمامي.

<?php

$handle = fopen("c:\\folder\\resource.txt", "r");

?>

mode

يُحدِّد هذا المعامل نوع الوصول المطلوب إلى المجرى. يمكن أن يكون أيُّ وضع من الأوضاع المذكور في الجدول التالي:

الوضع	الوصف
r	فتح الملف للقراءة فقط. سيوضع مؤشِّر الملف في بداية الملف.
r+‎	فتح الملف للقراءة والكتابة. سيوضع مؤشِّر الملف في بداية الملف.
w	فتح الملف للكتابة فقط. سيوضع مؤشِّر الملف في بداية الملف ويُزال كامل محتوى الملف إن كان موجودًا. إن كان الملف غير موجود، فستحاول الدالة إنشاءه.
w+‎	فتح الملف للكتابة والقراءة. سيوضع مؤشِّر الملف في بداية الملف ويٌزال كامل محتوى الملف إن كان موجودًا. إن كان الملف غير موجود، فستحاول الدالة إنشاءه.
a	فتح الملف للكتابة فقط. سيوضع مؤشِّر الملف في نهاية الملف. إن لم يكن الملف موجودًا، فستحاول الدالة إنشاءه. لن يكون للدالة fseek()‎ أي تأثير في هذا الوضع إذ ستُضاف المحتويات التي ستُكتب في نهاية الملف دومًا.
a+‎	فتح الملف للكتابة والقراءة. سيوضع مؤشِّر الملف في نهاية الملف. إن لم يكن الملف موجودًا، فستحاول الدالة إنشاءه. لن يكون للدالة fseek()‎ أي تأثير في هذا الوضع إذ ستُضاف المحتويات التي ستُكتب في نهاية الملف دومًا.
x	إنشاء الملف ثمَّ فتحه للكتابة فقط. سيوضع مؤشِّر الملف في بداية الملف. إن كان الملف موجودًا، فسيفشل استدعاء الدالة fopen()‎ وستعيد القيمة FALSE وستولِّد خطأً من المستوى E_WARNING. إن لم يكن الملف موجودًا ،فستحاول الدالة إنشاءه. هذا الوضع مماثل تمامًا لاستدعاء النظام للدالة open(2)‎ الأساسيَّة مع تمرير الرايتين O_EXCL | O_CREAT إليها.
x+‎	إنشاء الملف ثمَّ فتحه للكتابة والقراءة، وكلُّ ما تبقَّى مماثل تمامًا للوضع 'x'.
c	فتح الملف للكتابة. إن لم يكن الملف موجودًا، فستحاول الدالة إنشاءه. إن كان الملف موجودًا، فلن يُمسح محتوى الملف (خلافًا للوضع 'w') ولن يفشل استدعاء الدالة (كما هو الحال في الوضع 'x'). سيوضع مؤشِّر الملف في بداية الملف. هذا الوضع مناسب إن كنت ترغب في حماية الملف وقفله (انظر الدالة flock()‎) قبل أن تُعدِّل عليه، إذ سيؤدي استعمال الوضع 'c' في مثل هذه الحالة إلى إزالة محتوى الملف قبل تطبيق الحماية عليه. (إن كان إزالة المحتوى مرغوبًا فيه، فيمكن حينئذٍ استعمال الدالة ftruncate()‎ بعد طلب الحماية).
c+‎	فتح الملف للكتابة والقراءة، وكلُّ ما تبقَّى مماثل تمامًا للوضع 'c'.
e	تفعيل الراية close-on-exec على واصف الملف المفتوح، وهذا متاح في PHP التي تُفسَّر على الأنظمة المتوافقة مع معيار POSIX.1-2008 فقط.

ملاحظة: يختلف كلُّ نظام تشغيل عن الآخر أو حتى إصدارات أو توزيعات هذا النظام عن غيرها بطريقة إنهاء السطر. عندما تكتب نصًا في ملف وأردت إدراج فاصل سطري فأنت بحاجة إلى استعمال محرف أو محارف نهاية السطر الصحيحة المُعرَّفة في نظام تشغيلك. تستعمل الأنظمة الشبيهة بيونكس المحرف ‎\n لنهاية السطر، أمَّا الأنظمة التي تعتمد على ويندوز فتستعمل المحرفين ‎\r\n لهذ الغرض. إن استعملت محرف نهاية السطر الخطأ أثناء الكتابة على الملفات، فقد لا تتعرَّف التطبيقات الأخرى التي تفتح هذه الملفات على نهاية السطر وسيظهر المحتوى آنذاك بشكل خطأ.

يوفر نظام ويندوز وسيلة لتحويل محرف نهاية السطر (وهي راية وضع التحويل النصي 't') من المحرف ‎\n إلى ‎\r\n عند فتح الملفات. على النقيض، يمكن استعمال الراية 'b' لتفعيل الوضع الثنائي وبذلك لن يُحوَّل أو يتغيَّر أيَّ شيء من بياناتك. يمكنك استعمال هاتين الرايتين (الراية 't' أو الراية 'b') بتمرير إحدهما في نهاية قيمة المعامل mode أي بجعل إحداهما آخر محرف من قيمة هذا المعامل.

يعتمد وضع التحويل الافتراضي على SAPI وعلى إصدار PHP المُستعمل، لذا حبَّذا استخدام الراية الملائمة بدقَّة لتسهيل التنقل بين المنصات. يجب عليك استعمال الراية 't' إن كنت تعمل على ملفات ذات نصوص صرفة (plain-texts) وكنت تستخدم المحرف ‎\n لتحديد نهاية السطر في سكربتك؛ يستثنى في هذه الحالة أن تكون ملفاتك قابلة للقراءة باستعمال تطبيقات تشبه المفكرة (notepad). أمَّا مع بقية الحالات الأخرى فيجب عليك استعمال الراية 'b'.

إن لم تستعمل الراية 'b' عند العمل على ملفات بالنظام الثنائي، فقد تواجه مشكلات غريبة مع بياناتك من ضمنها عطب في ملفات الصور ومشكلات غير متوقعة مع المحرفين ‎\r\n.

ملاحظة: يوصى وبشدَّة استعمال الراية 'b' دومًا عند فتح الملفات مع الدالة fopen()‎ من أجل تحقيق قابلية التنقل بين المنصات.

ملاحظة: يوصى وبشدة مجدَّدًا إعادة كتابة شيفرة تستعمل أو تعتمد فيها على الوضع 't' لاستعمال محرف نهاية السطر الصحيح وعلى الوضع 'b' عوضًا عن 't' في الحالات الأخرى.

use_include_path

معامل اختياري، ويمكن أن تكون قيمته 1 أو TRUE إن أردت أن يُبحث على الملف في المسار المُضمَّن include_path أيضًا.

context

مورد محتوى صحيح أُنشئ باستعمال الدالة stream_context_create()‎.

ملاحظة: أُضيف دعم المحتوى منذ إصدار PHP 5.0.0. راجع قسم المجرى (stream) للمزيد من الشرح عن المحتوى (context).

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

يُعاد مورد يشير إلى الملف عند نجاح العمليَّة، أو القيمة FALSE عند فشلها أو وجود خطأ ما.

أخطاء واستثناءات

سيُولَّد خطأ من المستوى E_WARNING إن فشلت عمليَّة فتح الملف. تستطيع استعمال المحرف @ لإخفاء هذا التحذير.

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

الإصدار	الوصف
7.0.16، 7.1.2	إضافة الوضع 'e'.
5.2.6	إضافة الوضع 'c' والوضع 'c+‎'.
4.3.2	أًصبح الوضع الافتراضي بدءًا من الإصدار PHP 4.3.2 هو الوضع الثنائي والذي يُفرِّق بين الوضع النصي والثنائي. إن ظهرت أيَّة مشاكل في سكربتك بعد ترقية إصدار PHP لديك، فجرب استعمال الراية 't' إلى أن تنشئ سكربتات ذات قابليَّة للتنقل كما أشرنا إلى ذلك آنفًا.

أمثلة

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

<?php
$handle = fopen("/home/rasmus/file.txt", "r");
$handle = fopen("/home/rasmus/file.gif", "wb");
$handle = fopen("http://www.example.com/", "r");
$handle = fopen("ftp://user:password@example.com/somefile.txt", "w");
?>

ملاحظات

تحذير: سيجبر الخادم Microsoft IIS البروتوكول على إغلاق الاتصال دون إرسال close_notify عند استعمال SSL. ستُولِّد PHP تقريرًا عن ذلك "SSL: Fatal Protocol Error" عندما تصل إلى نهاية البيانات. يجب لتجنب الوقوع في هذه المشكلة تعيين قيمة الموجِّه error_reporting بتخفيضها إلى مستوى لا يتضمن أي تحذيرات. يمكن أن تكتشف PHP أخطاء الخادم IIS البرمجيَّة عند فتح مجرى باستعمال البروتوكول http://‎ وستحذف حينئذٍ التنبيه. وعند استعمال الدالة fsockopen()‎ لإنشاء مقبس ssl://‎، فيكون المُطوِّر مسؤولًا عن اكتشاف هذا التحذير وإزالته.

إن كان الوضع الآمن (safe mode) مفعَّلًا، فستتحقَّق PHP فيما إذا كان المجلَّد الذي يحتوي على السكربت أو الملف المراد إجراء العمليَّة عليه يملك معرف المستخدم المالك (UID) ذاته الذي يملكه السكربت الذي يُنفَّذ آنذاك.

إن كنت تواجه مشكلات تتعلَّق بالقراءة من والكتابة على الملفات وكنت تستعمل وحدة PHP الخاصة بالخادم، فتذكر أن تتأكَّد إن كانت تلك الملفات أو المجلَّدات متاحةً لوصول عمليات الخادم إليها.

غالبًا ما تنجح العمليَّة التي تطبقها هذه الدالة عندما يكون المعامل filename مجلدًا. إن لم تكن متأكدًا من أنَّ المعامل filename مجلدٌ أو ملف، فاستعمل الدالة is_dir()‎ قبل استدعاء الدالة fopen()‎.

انظر أيضًا

• الدالة fclose()‎: إغلاق مؤشر ملف مفتوح.
• الدالة popen()‎: تفتح عمليَّة وتشير إليها بمؤشر شبيه بمؤشر ملف.
• الدالة fsockopen()‎: تفتح اتصالًا بالإنترنت أو بمقبس نطاق يونكس (Unix domain socket).
• الدالة fgets()‎: تجلب سطرًا واحدًا من ملف.
• الدالة fread()‎: تقرأ من الملف بطريقة آمنة ثنائيًّا.
• الدالة fwrite()‎: تكتب على الملف بطريقة آمنة ثنائيًّا.
• الدالة file()‎: تقرأ الملف بأكمله ثمَّ تضع محتوياته في مصفوفة.
• الدالة file_exists()‎: تتحقَّق من وجود الملف أو المجلد.
• الدالة is_readable()‎: تتحقَّق إن كان الملف موجودًا وقابلًا للقراءة.
• الدالة stream_context_create()‎: تنشئ محتوى مجرى.
• الدالة stream_set_timeout()‎: تضبط مهلة المجرى.
• الدالة umask()‎: تغيِّر القيمة الحالية للقناع umask.

مصادر

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