PHP/fgetcsv

(PHP 4, PHP 5, PHP 7)

تَجلُب الدالة fgetcsv()‎ سطرًا واحدًا من ملف ذي الصيغة CSV (اختصارًا للعبارة comma-separated values) وتحلِّله ثمَّ تعيد مصفوفة بالقيم التي قرأتها.

الوصف

array fgetcsv ( resource $handle [, int $length = 0 [, string$delimiter = "," [, string $enclosure = '"' [, string $escape = "\\"]]]] )

تشبه هذه الدالة إلى حدٍّ كبير الدالة fgets()‎ باستثناء أنَّها تحلِّل السطر الذي تجلبه من ملف بصيغة CSV إلى حقول ثمَّ تعيد مصفوفةً تحوي تلك الحقول التي قرأتها من ذلك الملف.

المعاملات

handle

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

length

عدد المحارف المراد جلبها، ويجب أن يكون أكبر من أطول سطر تبحث عنه في الملف ذي الصيغة CSV (مصافًا له محارف نهاية السطر الزائدة). إن لم يكن كذلك، فسيُجزَّأ السطر إلى أجزاءٍ عدد محارفها هي القيمة length المعطاة، وربما قد يحدث التقسيم حينئذٍ داخل حدود الحقل ما لم يكن خارجه.

إن لم تحدَّد قيمة هذا المعامل أو كانت قيمته 0 عند استعمال إصدار PHP 5.1.0 وما بعده، فلن يكون هنالك حدٌّ أقصى لطول السطر وهذا قد يُبطِّئ الأداء بعض الشيء.

delimiter

معامل اختياري. يحدِّد المحرف المستعمل في الفصل بين الحقول، ويجب أن يكون محرفًا واحدًا فقط.

enclosure

معامل اختياري. يحدِّد المحرف المستعمل في تعيين حدود الحقل، ويجب أن يكون محرفًا واحدًا فقط.

escape

معامل اختياري. يحدِّد المحرف المستعمل في تهريب المحارف الأخرى، ويجب أن يكون محرفًا واحدًا فقط.

ملاحظة: يُهرَّب عادةً محرف حدُّ الحقل enclosure ضمن الحقل بمضاعفته، ويمكن أيضًا استعمال محرف التهريب عوضًا عن ذلك. أي يكون للقيمة "" والقيمة "\ المعنى ذاته في حال استعمال القيمة الافتراضيَّة للمعامل enclosure والمعامل escape. بغض النظر عن أنَّ محرف التهريب escape يسمح بتهريب محرف حد الحقل enclosure إلَّا أنَّه لا يملك معنًى خاصًا ولا حتى يُقصد به تهريب نفسه.

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

تُعاد مصفوفة تحتوي على الحقول المقروءة.

ملاحظة: سيُمثَّل السطر الفارغ الموجود في الملف CSV على أنَّه حقل واحد ذي قيمة فارغة NULL وستُعاد حينذاك مصفوفة تحتوى على قيمة فارغة NULL، ولن تعامل مثل هذه الحالة على أنَّها خطأ.

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

ستُعاد القيمة NULL إن كان المعامل handle غير صحيح، أو القيمة FALSE عند ظهور أخطاء أخرى من ضمنها الوصول إلى نهاية الملف (EOF).

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

الإصدار	الوصف
5.3.0	إضافة المعامل escape.
5.1.0	أصبح المعامل length اختياريًّا، وقيمته الافتراضيَّة 0 وتعني أنَّه لا يوجد حدٌّ أقصى لطول السطر.
4.3.5	أصبحت الدالة fgetcsv()‎ آمنة ثنائيًّا.

أمثلة

المثال 1: استعمال الدالة fgetcsv()‎ لقراءة كامل محتوى ملف وطباعته

<?php
$row = 1;
if (($handle = fopen("test.csv", "r")) !== FALSE) {
    while (($data = fgetcsv($handle, 1000, ",")) !== FALSE) {
        $num = count($data);
        echo "<p> $num fields in line $row: <br /></p>\n";
        $row++;
        for ($c=0; $c < $num; $c++) {
            echo $data[$c] . "<br />\n";
        }
    }
    fclose($handle);
}
?>

ملاحظات

تأخذ هذه الدالة إعدادات المحليَّة (locale) بالحسبان. إن كانت قيمة  LC_CTYPE مثلًا en_US.UTF-8، فسيُقرأ الملف الذي تُرمَّز المحارف فيه ببايتٍ واحد بطريقة خطأ عند استعمال هذه الدالة.

انظر أيضًا

• الدالة str_getcsv()‎: تحلِّل سلسلة نصيَّة بصيغة CSV إلى مصفوفة.
• الدالة explode()‎: تجزِّئ سلسلة نصيَّة معيَّنة إلى سلاسل نصيَّة أصغر.
• الدالة file()‎: تقرأ ملفًا بأكمله ثمَّ تعيد مصفوفة بمحتواه.
• الدالة pack()‎: تُحزِّم البيانات في سلسلة نصيَّة بالنظام الثنائي.
• الدالة fputcsv()‎: تنسِّق سطرًا من البيانات بصيغة CSV ثمَّ تكتبه على ملف.

مصادر

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