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

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

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

الوصف

string file_get_contents ( string $filename [, bool $use_include_path= FALSE [, resource $context [, int $offset = 0 [, int $maxlen ]]]] )

تشبه هذه الدالة إلى حدٍّ كبير الدالة file()‎ باستثناء أنَّها تعيد محتوى الملف في سلسلة نصيَّة. يبدأ ذلك المحتوى عند الموقع offset ويكون بطول maxlen بايت. تعيد هذه الدالة عندما تفشل القيمة FALSE.

تعدُّ الدالة file_get_contents()‎ وسيلة مفضَّلة لقراءة محتوى ملف وتحويله إلى سلسلة نصيَّة إذ تَستخدم تقينات خريطة الذاكرة (memory mapping) لتحسين الأداء شرط أن تكون مدعومة من طرف نظام التشغيل.

ملاحظة: إن كنت تحاول فتح رابط URI يحتوي على محارف مميَّزة مثل الفراغات، فستحتاج إلى ترميز هذا الرابط أولًأ باستعمال الدالة urlencode()‎.

المعاملات

filename

اسم الملف المراد قراءته.

use_include_path

ملاحظة: يمكن بدءًا من إصدار PHP 5 أن يُستخدم الثابت FILE_USE_INCLUDE_PATH لتفعيل عمليَّة بحث المسار المُضمَّن (include path search). لن يكون ذلك ممكنًا إن كان وضع الإدخال الصارم (strict typing) فعالًا إذ يُعدُّ الثابت FILE_USE_INCLUDE_PATH عددًا صحيحًا (int). استعمل القيمة TRUE عوضًا عن ذلك.

context

مورد محتوى صحيح أُنشئ باستعمال الدالة stream_context_create()‎. إن لم تودَّ استعمال مورد مخصَّص، فيمكنك تخطي هذا المعامل باستعمال القيمة NULL.

offset

تُمثِّل قيمة هذا المعامل موقع بداية القراءة من المجرى الأساسي. إن كانت هذه القيمة سالبة، فستحدِّد موقع بداية القراءة انطلاقًا من نهاية المجرى.

بدء القراءة من موقع offset محدَّد غير مدعوم مع الملفات البعيدة. من الممكن البحث عن موقع محدَّد لبدء القراءة عنده في الملفات غير المحليَّة (non-local) وذلك باستعمال قيم صغيرة للمعامل offset. مع ذلك، لا يمكن التنبؤ بنتيجة هذا الأمر بسبب أنَّ المعامل offset يعمل مع المجرى المُخزَّن فقط.

maxlen

الطول الأقصى للبيانات التي ستُقرأ. القيمة الافتراضيَّة لهذا المعامل هي قراءة الملف حتى الوصول إلى نهايته. الجدير بالملاحظة أنَّ هذا المعامل يُطبَّق على المجرى المُعالج باستعمال المرشِّحات.

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

تُعاد البيانات التي قُرأت أو القيمة FALSE عند الفشل.

تحذير: تعيد هذه الدالة أحيانًا القيمة المنطقيَّة FALSE وتعيد أحيانًا أخرى قيمة غير منطقيَّة ولكنَّها تعادل القيمة FALSE، لذا استعمل المعامل === للتحقُّق من القيمة المُعادة. راجع قسم القيم المنطقيَّة (booleans) للاطلاع على المزيد من المعلومات.

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

سيُولَّد الخطأ E_WARNING إن لم يُعثر على الملف filename أو كانت قيمة المعامل maxlen أصغر من الصفر أو فشلت عمليَّة إيجاد الموقع offset المعطى في المجرى.

أمثلة

المثال 1: جلب محتوى الصفحة الرئيسيَّة لموقع ثمَّ إظهاره

<?php
$homepage = file_get_contents('http://www.example.com/');
echo $homepage;
?>

المثال 2: البحث في include_path

<?php
// <= PHP 5
$file = file_get_contents('./people.txt', true);
// > PHP 5
$file = file_get_contents('./people.txt', FILE_USE_INCLUDE_PATH);
?>

المثال 3: قراءة جزء من ملف

<?php
// قراءة 14 محرفًا بدءًا من المحرف الواحد والعشرين
$section = file_get_contents('./people.txt', FALSE, NULL, 20, 14);
var_dump($section);
?>

سيُظهر المثال السابق نتيجة شبيهة بالتالي:

string(14) "Bashir Ameen"

المثال 4: استعمال محتوى مجرى

<?php
// إنشاء مجرى
$opts = array(
  'http'=>array(
    'method'=>"GET",
    'header'=>"Accept-language: en\r\n" .
              "Cookie: foo=bar\r\n"
  )
);

$context = stream_context_create($opts);

//التي أنشئت آنفًا HTML فتح الملف باستعمال ترويسة 
$file = file_get_contents('http://www.example.com/', false, $context);
?>

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

الإصدار	الوصف
7.1.0	إضافة دعم القيم السالبة للمعامل offset.
5.1.0	إضافة المعامل offset والمعامل maxlen.

ملاحظات

هذه الدالة آمنة ثنائيًّا (binary safe).

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

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

انظر أيضًا

• الدالة file()‎: تقرأ محتويات الملف كاملةً وتضعها في مصفوفة.
• الدالة fgets()‎: تجلب سطرًا من ملف.
• الدالة fread()‎: تقرأ بطريقة آمنة ثنائيًّا من ملف.
• الدالة readfile()‎: تقرأ ملفًا وتُظهر محتواه.
• الدالة file_put_contents()‎: تكتب سلسلة نصيَّة على ملف.
• الدالة stream_get_contents()‎: تقرأ ما تبقَّى من المجرى وتضعه في سلسلة نصيَّة.
• الدالة stream_context_create()‎: تنشئ محتوى مجرى.
• ‎$http_response_header‎

مصادر

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