PHP/fputcsv

(PHP 4, PHP 5, PHP 7)

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

الوصف

int fputcsv ( resource $handle , array $fields [, string $delimiter = "," [, string $enclosure = '"' [, string $escape_char = "\\" ]]] )

تنسق هذه الدالة سطرًا من البيانات المُمرَّرة عبر المصفوفة fields بالصيغة CSV ثمَّ تكتبها على الملف الذي يشير إليه المورد handle (بعد أن تضيف في نهاية ذلك السطر محرف سطر جديد).

المعاملات

handle

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

fields

مصفوفة من القيم المراد كتابتها على الملف.

delimiter

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

enclosure

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

escape_char

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

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

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

يُعاد عدد المحارف التي كُتبت على الملف، أو القيمة FALSE عند فشل العمليِّة.

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

الإصدار	الوصف
5.5.4	إضافة المعامل escape_char.

أمثلة

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

<?php

$list = array (
    array('aaa', 'bbb', 'ccc', 'dddd'),
    array('123', '456', '789'),
    array('"aaa"', '"bbb"')
);

$fp = fopen('file.csv', 'w');

foreach ($list as $fields) {
    fputcsv($fp, $fields);
}

fclose($fp);
?>

سيبدو محتوى الملف file.csv بعد تنفيذ المثال السابق بالشكل:

aaa,bbb,ccc,dddd
123,456,789
"""aaa""","""bbb"""

ملاحظات

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

انظر أيضًا

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

مصادر

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