PHP/fread

(PHP 4, PHP 5, PHP 7)

تقرأ الدالة fread()‎ من ملف معيَّن بطريقة آمنة ثنائيًّا.

الوصف

string fread ( resource $handle , int $length )

تقرأ هذه الدالة عددًا محدودًا من البايتات (التي تحدَّدها قيمة المعامل length) من الملف الذي يشير إليه المورد handle. ستتوقَّف عمليَّة القراءة حال تحقُّق أحد الشروط التالية:

• إكمال قراءة البايتات التي تحدِّدها قيمة المعامل length.
• الوصول إلى نهاية الملف (EOF).
• حزمة من البيانات أًصبحت متاحة أو انتهاء مهلة المقبس (socket، وذلك عند القراءة من مجرى شبكة).
• إن خُزِّن المجرى الذي يُقرأ منه ولم يعد يشير إلى ملف، فستتوقَّف عمليَّة القراءة عند قراءة عدد من البايتات يساوي إلى حجم القطعة المُشكَّلة (chunk size، تكون عادةً 8192). يعتمد ذلك على البيانات المخزَّنة مسبقًا، وقد يكون حجم البيانات المُعادة أكبر من حجم تلك القطعة.

المعاملات

handle

مؤشِّر (pointer) يشير إلى ملف. يجب أن يكون سليمًا، ويشير إلى ملف فُتح بطريقة صحيحة باستعمال الدالة fopen()‎ أو الدالة fsockopen()‎ ولم يُغلق بعد باستعمال الدالة fclose()‎.

length

عدد البايتات المراد قراءتها.

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

تُعاد السلسلة النصيَّة التي قُرئت من الملف الذي يشير إليه المورد handle. إن حصل أي خطأ، فستُعاد القيمة FALSE.

أمثلة

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

<?php
// قراءة محتوى الملف بأكمله ووضعه في سلسلة نصيَّة
$filename = "/usr/local/something.txt";
$handle = fopen($filename, "r");
$contents = fread($handle, filesize($filename));
fclose($handle);
?>

المثال 2: قراءة ملف ذو محتوى ثنائي تحذير: إن استعملت نظامًا يفرِّق بين المحتوى النصِّي والثنائي للملفات (مثل نظام ويندوز)، فيجب فتح الملف بإضافة الراية 'b' في نهاية قيمة المعامل mode عند استدعاء الدالة fopen()‎.

<?php
$filename = "c:\\files\\somepic.gif";
$handle = fopen($filename, "rb");
$contents = fread($handle, filesize($filename));
fclose($handle);
?>

المثال 3: استعمال الدالة fread()‎ مع المحتوى البعيد عند القراءة من أي شيء لا يُعدُّ ملفًا محليًّا اعتياديًّا مثل المجرى الذي يقرأ من ملفات بعيدة أو الذي أُعيد باستعمال الدالة popen()‎ أو الدالة fsockopen()‎، فستتوقَّف عمليَّة القراءة عندما تتاح حزمة بيانات جديدة. أي يجب عليك حينئذٍ جمع البيانات سويَّةً في قطع (chunks) مثل ما هو موضَّح في المثال التالي:

<?php
//وما فوق PHP 5 إصدار 
$handle = fopen("http://www.example.com/", "rb");
$contents = stream_get_contents($handle);
fclose($handle);
?>

<?php
$handle = fopen("http://www.example.com/", "rb");
if (FALSE === $handle) {
    exit("Failed to open stream to URL");
}

$contents = '';

while (!feof($handle)) {
    $contents .= fread($handle, 8192);
}
fclose($handle);
?>

ملاحظات

• إن كنت تريد جلب محتوى الملف ووضعه في سلسلة نصيَّة فقط، فاستعمل الدالة file_get_contents()‎ إذ تتميَّز بأداء أفضل.
• الجدير بالذكر أنَّ الدالة fread()‎ تقرأ من الموقع الحالي لمؤشِّر الملف، لذا يمكن استعمال الدالة ftell()‎ لمعرفة الموقع الحالي للمؤشِّر، أو الدالة rewind()‎ لإرجاع المؤشِّر إلى موقع بداية الملف.

انظر أيضًا

• الدالة fwrite()‎: تكتب على الملف بطريقة آمنة ثنائيًّا.
• الدالة fopen()‎: تفتح ملفًا أو عنوان URL.
• الدالة popen()‎: تفتح عمليَّة وتشير إليها بمؤشر شبيه بمؤشر ملف.
• الدالة fsockopen()‎: تفتح اتصالًا بالإنترنت أو بمقبس نطاق يونكس (Unix domain socket).
• الدالة fgets()‎: تجلب سطرًا واحدًا من ملف محدَّد.
• الدالة fgetss()‎: تجلب سطرًا من ملف وتزيل وسوم HTML.
• الدالة fscanf()‎: تحلِّل المدخلات من ملف وفقًا لتنسيق محدَّد.
• الدالة file()‎: تقرأ الملف بأكمله ثمَّ تضع محتوياته في مصفوفة.
• الدالة fpassthru()‎: تُظهر ما تبقَّى من محتويات الملف.
• الدالة ftell()‎: تعيد الموقع الحالي لمؤشِّر القراءة من أو الكتابة على الملف.
• الدالة rewind()‎: تُرجع المؤشِّر إلى موقع بداية الملف.
• الدالة unpack()‎: تفرِّغ البيانات من سلسلة نصيَّة تحتوي على بيانات بالنظام الثنائي.

مصادر

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