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 экранируется внутри поля путём удвоения; однако как альтернативу разрешается использовать символ экранирования 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"""

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

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

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

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

＋Добавить

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

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