fputcsv()

Функция fputcsv() форматирует одну строку данных — переданную как PHP array — в строку CSV (comma-separated values) и записывает её в открытый файл. Это стандартный способ экспорта табличных данных, таких как отчёты, выгрузки из баз данных или таблицы, которые пользователи будут открывать в Excel, Google Sheets или LibreOffice.

На этой странице рассматриваются синтаксис и параметры, типичный цикл записи, то, как fputcsv() автоматически заключает в кавычки и экранирует специальные символы, способы управления разделителем и символом заключения, а также наиболее распространённые подводные камни (завершающий перенос строки, UTF-8 в Excel и изменяющееся значение по умолчанию для параметра $escape).

Синтаксис

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

Возвращаемое значение: количество записанных байт или false в случае ошибки.

Параметр $eol доступен начиная с PHP 8.1, а в PHP 9.0 значение по умолчанию для $escape изменено с "\\" на "". Для стабильного и переносимого вывода рекомендуется явно передавать escape: "".

Как работает fputcsv()

fputcsv() принимает один array и записывает ровно одну строку. Для экспорта таблицы функция вызывается один раз для каждой строки внутри цикла. Функция берёт на себя экранирование кавычками: любое поле, содержащее разделитель, символ заключения или перенос строки, автоматически оборачивается в символ заключения, а встроенные кавычки удваиваются.

Базовый процесс работы:

1. Создать array (или array arrays) с данными для экспорта.
2. Открыть целевой файл для записи с помощью fopen().
3. Вызвать fputcsv() один раз для каждой строки.
4. Закрыть файл с помощью fclose().

Базовый пример: запись CSV-файла

<?php

$data = [
    ['Name', 'Surname', 'Age', 'Gender'], // header row
    ['John', 'Doe', '30', 'Male'],
    ['Jane', 'Doe', '25', 'Female'],
    ['Bob', 'Smith', '40', 'Male'],
];

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

foreach ($data as $row) {
    fputcsv($file, $row);
}

fclose($file);

// Show what was written:
echo file_get_contents('people.csv');

Вывод:

Name,Surname,Age,Gender
John,Doe,30,Male
Jane,Doe,25,Female
Bob,Smith,40,Male

Первый array записывается как строка заголовка, а каждый последующий array становится одной строкой данных.

Автоматическое заключение в кавычки и экранирование

Вам не нужно самостоятельно заключать поля в кавычки — fputcsv() сама определяет, когда это необходимо. Поле заключается в кавычки только в том случае, если оно содержит разделитель, перенос строки или символ заключения.

<?php

$file = fopen('php://output', 'w'); // write straight to the browser/CLI

fputcsv($file, ['Plain', 'Has, comma', 'Has "quotes"', "Two\nlines"]);

fclose($file);

Вывод:

Plain,"Has, comma","Has ""quotes""","Two
lines"

Обратите внимание: Plain остаётся без изменений, поле с запятой оборачивается в кавычки, встроенные двойные кавычки удваиваются (""), а значение с переносом строки заключается в кавычки, чтобы перенос сохранился. Поток php://output удобен для тестирования или для потоковой передачи загрузки без создания временного файла.

Пользовательский разделитель и символ заключения

Чтобы создать файл с разделителем в виде табуляции или точки с запятой, передайте аргумент $separator. Во многих европейских локалях файлы с разделителем-точкой с запятой корректнее открываются в Excel.

<?php

$file = fopen('php://output', 'w');

// Semicolon delimiter
fputcsv($file, ['John', 'Doe', '30'], ';');

// Tab delimiter
fputcsv($file, ['Jane', 'Doe', '25'], "\t");

fclose($file);

Вывод:

John;Doe;30
Jane	Doe	25

Распространённые подводные камни

• Завершающий перенос строки. fputcsv() всегда добавляет завершающий перенос строки, поэтому файл заканчивается пустой строкой. При последующем чтении с помощью fgetcsv() это безвредно, но может удивить при побайтовом сравнении.
• UTF-8 в Excel. Excel требует метку порядка байт UTF-8 (BOM) для корректного отображения символов с диакритикой. Запишите её перед первой строкой: fwrite($file, "\xEF\xBB\xBF");. См. fwrite().
• Параметр $escape. Устаревшее экранирование обратной косой чертой может повредить поля, которые законно содержат \. Передайте escape: "" (PHP 7.4+) для чистого вывода в соответствии с RFC 4180; это также соответствует новому умолчанию PHP 9.
• Всегда проверяйте возвращаемое значение. fputcsv() возвращает false в случае ошибки (например, при переполнении диска или потоке только для чтения). Оберните запись в обработку ошибок для производственных экспортов.
• Удобная альтернатива. Чтобы записать всю string в файл за один вызов, см. file_put_contents(); используйте fputcsv(), когда требуется корректное CSV-экранирование для каждой строки.

Чтение файла обратно

Естественным аналогом fputcsv() является fgetcsv(), которая разбирает одну строку CSV обратно в array:

<?php

$file = fopen('people.csv', 'r');

while (($row = fgetcsv($file)) !== false) {
    echo implode(' | ', $row), PHP_EOL;
}

fclose($file);

Если у вас уже есть CSV-string в памяти, а не файл, используйте вместо неё str_getcsv().

Заключение

fputcsv() — это идиоматический способ экспорта данных array в CSV в PHP: она автоматически обрабатывает заключение разделителей в кавычки и экранирование кавычек, поддерживает пользовательские разделители и естественно сочетается с fopen() и fclose(). Для переносимого вывода передавайте escape: "", а при назначении файла для Excel добавляйте UTF-8 BOM. Для чтения данных обратно используйте fgetcsv().

Практика