PHP/fgets

(PHP 4, PHP 5, PHP 7)

تَجلُب الدالة fgets()‎ سطرًا واحدًا من ملف معيَّن.

الوصف

string fgets ( resource $handle [, int $length ] )

تجلب هذه الدالة سطرًا واحدًا من الملف الذي يشير إليه المورد handle.

المعاملات

handle

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

length

إن حُدِّدت قيمة هذا المعامل، فستتوقف عمليَّة القراءة عند البايت length - 1 أو عند الوصول لنهاية السطر (وستُعاد قيمة ذلك السطر بأكمله) أو عند الوصول لنهاية الملف (EOF).

إن لم تُعطَ قيمة هذا المعامل، فستستمر عمليَّة القراءة من المجرى حتى الوصول إلى نهاية السطر.

ملاحظة: سيكون طول السطر الافتراضي عند عدم تحديد قيمة المعامل length هو 1024 وذلك حتى إصدار PHP 4.3.0. إن كان طول أغلب الأسطر في الملف أكبر من 8 كيلوبايت، فيفضَّل تحديد طول السطر الأقصى حتى تكون الموارد ذات كفاءة أكبر في سكربتك.

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

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

إن حصل أي خطأ، فستُعاد القيمة FALSE.

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

الإصدار	الوصف
4.3.5	أصبحت الدالة fgets()‎ آمنة ثنائيًّا.

أمثلة

المثال 1: استعمال الدالة fgets()‎ لقراءة كلِّ سطر على حدة من أسطر ملف

<?php
$handle = @fopen("/tmp/inputfile.txt", "r");
if ($handle) {
    while (($buffer = fgets($handle, 4096)) !== false) {
        echo $buffer;
    }
    if (!feof($handle)) {
        echo "Error: unexpected fgets() fail\n";
    }
    fclose($handle);
}
?>

ملاحظات

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

الأشخاص الذين اعتادوا على مبدأ عمل الدالة fgets()‎ في C سيلاحظون الفرق في الطريقة التي تعاد فيها القيمة عند الوصول إلى نهاية الملف (EOF).

انظر أيضًا

• الدالة fread()‎: تقرأ بطريقة آمنة ثنائيًّا من ملف.
• الدالة fopen()‎: تفتح ملفًا أو عنوان URL.
• الدالة popen()‎: تفتح عمليَّة وتشير إليها بمؤشر شبيه بمؤشر ملف.
• الدالة fsockopen()‎: تفتح اتصالًا بالإنترنت أو بمقبس نطاق يونكس (Unix domain socket).
• الدالة fgetc()‎: تجلب محرفًا واحدًا من ملف محدَّد.
• الدالة fgetss()‎: تجلب سطرًا من ملف وتزيل وسوم HTML.
• الدالة stream_get_line()‎: تجلب سطرًا من مودر المجرى والذي ينتهي بفاصل معيَّن.
• الدالة stream_set_timeout()‎: تحدِّد مهلة المجرى.

مصادر

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