PHP/file

(PHP 4, PHP 5, PHP 7)

تقرأ الدالة file()‎ الملف ثمَّ تضع كلَّ محتوياته في مصفوفة.

الوصف

array file ( string $filename [, int $flags = 0 [, resource $context]] )

تعيد هذه الدالة مصفوفة تضم كلَّ محتويات الملف filename.

ملاحظة: يمكنك استعمال الدالة file_get_contents()‎ لجلب كلِّ محتويات الملف ووضعها في سلسلة نصيَّة عوضًا عن مصفوفة.

المعاملات

filename

اسم الملف المراد جلب محتوياته.

فائدة: يمكن استعمال عنوان URL عوضًا عن اسم الملف مع المعامل filename شرط أن يُفعَّل الضبط "fopen wrapper". راجع صفحة الدالة fopen()‎ للمزيد من التفاصيل حول كيفيَّة تحديد المعامل filename. راجع أيضًا صفحة البروتوكولات المدعومة للحصول على المزيد من المعلومات حول القدرات التي تمتلكها ، والملاحظات المتعلِّقة باستعمالها، والمعلومات التي يمكن أن تقدمها عن أي مُتغيرات مُعرَّفة مسبقًا.

flags

يمكن أن يكون هذا المعامل الاختياري واحدًا أو أكثر من الثوابت الموضَّحة في الجدول التالي.

الثابت	الوصف
FILE_USE_INCLUDE_PATH	البحث عن الملف في المجلَّد المضمَّن include_path.
FILE_IGNOR_NEW_LINES	عدم إضافة محرف سطر جديد في نهاية كل عنصر من عناصر المصفوفة المُعادة.
FILE_SKIP_EMPTY_LINES	تجاهل الأسطر الفارغة.

context

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

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

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

تُعاد جميع محتويات الملف في مصفوفة؛ يحوي كلُّ عنصر من عناصر المصفوفة سطرًا واحدًا من محتويات الملف بالإضافة إلى وجود محرف سطر جديد في نهايته.

تُعاد القيمة FALSE عند فشل العمليَّة.

ملاحظة: سيتضمَّن كلُّ سطر موجود في عناصر المصفوفة المعُادة على محرف نهاية السطر ما لم يُستعمل الثابت FILE_IGNOR_NEW_LINE. إن أردت إزالة محرف نهاية السطر دون استعمال ذلك الثابت، فيمكنك استعمال الدالة rtrim()‎.

ملاحظة: إن لم تتعرَّف PHP على نهاية السطر عند قراءة ملفات موجودة على نظام Macintosh أو أُنشأت باستعماله، ففعِّل خيار auto_detect_line_endings من ضبط التشغيل (runtime configuration) إذ سيساعد ذلك على حلِّ المشكلة.

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

سيُولَّد الخطأ E_WARNING إن لم يُعثر على الملف filename.

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

الإصدار	الوصف
4.3.0	أصبحت هذه الدالة آمنة ثنائيًّا (binary safe).

أمثلة

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

<?php
//HTTP عبر بروتوكول URL لرابط HTML سنوضِّح في هذا المثال كيفيَّة جلب محتوى صفحة 
$lines = file('http://www.example.com/');

//HTML استعمال حلقة تكرار مع المصفوفة المُعادة لإظهار محتواها على أنَّه شيفرة 
//بالإضافة إلى إظهار أرقام الأسطر
foreach ($lines as $line_num => $line) {
    echo "Line #<b>{$line_num}</b> : " . htmlspecialchars($line) . "<br />\n";
}

//file_get_contents() مثال آخر عن جلب محتوى صفحة ويب ووضعه في سلسلة نصيَّة. انظر أيضًا الدالة
$html = implode('', file('http://www.example.com/'));

//PHP 5 الاختياري انطلاقًا من إصدار flags استعمال المعامل 
$trimmed = file('somefile.txt', FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);
?>

ملاحظات

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

انظر أيضًا

• الدالة fopen()‎: تفتح ملفًا أو عنوان URL.
• الدالة popen()‎: تفتح عمليَّة وتشير إليها بمؤشر شبيه بمؤشر ملف.
• الدالة fsockopen()‎: تفتح اتصالًا بالإنترنت أو بمقبس نطاق يونكس (Unix domain socket).
• الدالة file_get_contents()‎: تقرأ الملف ثمَّ تضع كلَّ محتوياته في سلسلة نصيَّة.
• الدالة readfile()‎: تقرأ ملفًا وتُظهر محتواه.
• الدالة stream_context_create()‎: تنشئ محتوى مجرى.
• العبارة ‎include: تعمل على تضمين ومعالجة ملف محدَّد.

مصادر

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