(PHP 5 >= 5.4.0, PHP 7, PHP 8)
SplFileObject::fputcsv — Записывает массив полей как CSV-строки
$fields,$separator = ",",$enclosure = "\"",$escape = "\\",$eol = "\n"
Метод записывает массив полей fields в файл как CSV-строку.
fieldsМассив значений.
separator
Параметр устанавливает символ-разделитель полей и принимает только один однобайтовый символ.
Значение по умолчанию равно запятой — , или символу, который
установили методом SplFileObject::setCsvControl().
enclosure
Параметр устанавливает символ-ограничитель значений в полях и принимает
только один однобайтовый символ. Значение по умолчанию равно двойной кавычке — "
или значению, которое установили методом
SplFileObject::setCsvControl().
escape
Параметр устанавливает символ экранирования и принимает не больше одного однобайтового символа.
Значение по умолчанию равно обратному слешу
\ или значению, которое установили методом
SplFileObject::setCsvControl().
Пустая строка "" отключает внутренний механизм экранирования.
Замечание: Обычно символ ограничителя значений —
enclosureэкранируется внутри поля путём удвоения; однако как альтернативу разрешается использовать символ экранированияescape. Поэтому для стандартных значений параметра смысл значений""и\"одинаков. Символ экранирования —escapeне несёт отдельного смысла, кроме экранирования символа ограничителя значений —enclosure; он даже не экранирует сам себя.
Начиная с PHP 8.4.0 полагаться на значение по умолчанию,
которое содержит параметр escape, не рекомендуют.
Значение потребуется указать явно: позиционно,
как именованный аргумент
или методом SplFileObject::setCsvControl().
eol
Необязательный параметр eol
устанавливает пользовательскую последовательность конца строки.
Строка в CSV-формате иногда перестаёт соответствовать стандарту » RFC 4180
или не выдерживает обмена информацией с PHP-функциями
для работы с CSV-строками, если для символа экранирования escape устанавливают значение,
которое отличается от пустой строки "".
Значение по умолчанию для параметра escape — "\\",
поэтому рекомендуют явно указывать пустую строку. Значение по умолчанию изменят в будущей версии PHP, но не раньше PHP 9.0.
Замечание:
Метод заэкранирует символ ограничителя полей
enclosureпутём удвоения, если поле содержит символ ограничителя, если только прямо перед символом ограничителя не стоит символ экранированияescape.
Метод возвращает длину строки, которую записал, или false, если возникла ошибка.
Функция выбрасывает ошибку ValueError,
если аргументы для разделителя полей separator или ограничителя значений enclosure
содержат значение короче одного байта.
Функция выбрасывает ошибку ValueError,
если длина значения аргумента escape не равна одному байту или передали пустую строку.
| Версия | Описание |
|---|---|
| 8.4.0 |
Вызов функции без явной передачи значения в параметр escape
устарел.
|
| 8.1.0 |
Добавили необязательный параметр eol.
|
| 7.4.0 |
Параметр escape теперь принимает пустую строку
для отключения механизма экранирования.
|
Пример #1 Пример записи массива полей как строки в CSV-формате методом SplFileObject::fputcsv()
<?php
$list = array (
array('aaa', 'bbb', 'ccc', 'dddd'),
array('123', '456', '789'),
array('"aaa"', '"bbb"')
);
$file = new SplFileObject('file.csv', 'w');
foreach ($list as $fields) {
$file->fputcsv($fields);
}
?>Приведённый пример записывает следующие строки в файл file.csv:
aaa,bbb,ccc,dddd 123,456,789 """aaa""","""bbb"""