SplFileObject::fputcsv

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

SplFileObject::fputcsv — Записывает массив полей как CSV-строки

Описание

public function SplFileObject::fputcsv(
    array $fields,
    string $separator = ",",
    string $enclosure = "\"",
    string $escape = "\\",
    string $eol = "\n"
): int|false

Метод записывает массив полей fields в файл как CSV-строку.

Список параметров

fields: Массив значений.
separator: Параметр устанавливает символ-разделитель полей и принимает только один однобайтовый символ. Значение по умолчанию равно запятой — , или символу, который установили методом SplFileObject::setCsvControl().
enclosure: Параметр устанавливает символ-ограничитель значений в полях и принимает только один однобайтовый символ. Значение по умолчанию равно двойной кавычке — " или значению, которое установили методом SplFileObject::setCsvControl().
escape: Параметр устанавливает символ экранирования и принимает не больше одного однобайтового символа. Значение по умолчанию равно обратному слешу \ или значению, которое установили методом SplFileObject::setCsvControl(). Пустая строка "" отключает внутренний механизм экранирования.

Внимание
Дублирование символа enclosure внутри обозначенных символом границ вернёт в результате разбора входного потока один символ enclosure. Параметр escape работает по-другому: при добавлении символа escape перед символом enclosure оба символа вернутся в результате разбора, поэтому со стандартными значениями параметров CSV-строка наподобие "a""b","c\"d" разберётся на два поля — a"b и c\"d.

Внимание
Начиная с 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"""

Смотрите также

SplFileObject::fgetcsv() - Получает строку из файлового указателя и разбирает по CSV-полям
SplFileObject::setCsvControl() - Устанавливает символы разделителя, ограничителя и экранирования для CSV-полей
SplFileObject::getCsvControl() - Получает символы разделителя, ограничителя и экранирования CSV-полей
fputcsv() - Формирует строку в CSV-формате и записывает строку в файловый указатель
fgetcsv() - Получает строку из файлового указателя и разбирает по CSV-полям
str_getcsv() - Разбирает CSV-строку в массив

Нашли ошибку?

Инструкция • Исправление • Сообщение об ошибке

＋Добавить

Примечания пользователей

Пользователи ещё не добавляли примечания для страницы