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

# 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-строку в массив

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open