PHP Manual»Функции файловой системы»fputcsv

fputcsv

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

fputcsv — Формирует строку в CSV-формате и записывает строку в файловый указатель

Описание

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

Функция fputcsv() формирует из массива полей fields строку в CSV-формате, завершает её символом перевода строки и записывает строку в файловый указатель stream.

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

stream: Требуется допустимый указатель на файл, который успешно открыли функцией fopen() или функцией fsockopen() и ещё не закрыли функцией fclose().
fields: Массив строк (string).
separator: Параметр separator устанавливает разделитель полей и принимает только один однобайтовый символ.
enclosure: Параметр enclosure устанавливает символ для обозначения границ значения поля и принимает только один однобайтовый символ; часть строки внутри ограничителей разбирается как значение одного поля, даже если содержит символ-разделитель.
escape: Параметр escape устанавливает символ экранирования и принимает только один однобайтовый символ или пустую строку. Пустая строка "" отключает внутренний механизм экранирования.

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

Внимание
Начиная с PHP 8.4.0 вызов без явной передачи аргумента escape устарел. Символ экранирования теперь передаётся при каждом вызове функции позиционно или как именованный аргумент, даже если значение аргумента совпадает с предустановленным значением параметра.
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-строки в файл функцией fputcsv()

<?php

$list = [
    ['aaa', 'bbb', 'ccc', 'dddd'],
    ['123', '456', '789'],
    ['"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"""

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

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