Получает строку из файлового указателя и разбирает по CSV-полям

# SplFileObject::fgetcsv

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

SplFileObject::fgetcsv — Получает строку из файлового указателя и разбирает по CSV-полям

### Описание

public function SplFileObject::fgetcsv(string `$separator` = ",", string `$enclosure` = "\"", string `$escape` = "\\"): array|false

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

> Замечание: Функция учитывает региональный настройки. Поэтому функция иногда неправильно разбирает данные в отдельных однобайтовых кодировках, если значение константы `LC_CTYPE` равно `en_US.UTF-8`.

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

`separator`

  Параметр устанавливает символ-разделитель полей и принимает только один однобайтовый символ. Значение по умолчанию равно запятой — `,` или символу, который установили методом SplFileObject::setCsvControl().

`enclosure`

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

`escape`

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

  Внимание

  Обычно символ ограничителя значений — `enclosure` экранируется внутри поля путём удвоения; однако как альтернативу разрешается использовать символ экранирования `escape`. Поэтому для стандартных значений параметра смысл значений `""` и `\"` одинаков. Символ экранирования — `escape` не несёт отдельного смысла, кроме экранирования символа ограничителя значений — `enclosure`; он даже не экранирует сам себя.

  Внимание

  Начиная с PHP 8.4.0 полагаться на значение по умолчанию, которое содержит параметр `escape`, не рекомендуют. Значение потребуется указать явно: позиционно, как именованный аргумент или методом SplFileObject::setCsvControl().

Внимание

Строка в CSV-формате иногда перестаёт соответствовать стандарту » RFC 4180 или не выдерживает обмена информацией с PHP-функциями для работы с CSV-строками, если для символа экранирования `escape` устанавливают значение, которое отличается от пустой строки `""`. Значение по умолчанию для параметра `escape` — `"\\"`, поэтому рекомендуют явно указывать пустую строку. Значение по умолчанию изменят в будущей версии PHP, но не раньше PHP 9.0.

### Возвращаемые значения

Метод возвращает массив, который содержит данные прочитанной строки, или `false`, если возникла ошибка.

> Замечание:

> Пустая строка в CSV-файле возвращается как массив с единственным элементом `null`, если только через побитовое ИЛИ не указали константы `SplFileObject::SKIP_EMPTY | SplFileObject::DROP_NEW_LINE`, с которыми пустые строки пропускаются.

### Ошибки

Функция выбрасывает ошибку ValueError, если аргументы для разделителя полей `separator` или ограничителя значений `enclosure` содержат значение короче одного байта.

Функция выбрасывает ошибку ValueError, если длина значения аргумента `escape` не равна одному байту или передали пустую строку.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Вызов функции без явной передачи значения в параметр `escape` устарел.
7.4.0 | Теперь параметр `escape` принимает пустую строку для отключения внутреннего механизма экранирования.

### Примеры

Пример #1 Пример получения и разбора строки по CSV-полям методом SplFileObject::fgetcsv()

    <?php

    $file = new SplFileObject("data.csv");

    while (!$file->eof()) {
        var_dump($file->fgetcsv());
    }

    ?>

Пример #2 Пример разбора строк с флагом `SplFileObject::READ_CSV`

    <?php

    $file = new SplFileObject("animals.csv");
    $file->setFlags(SplFileObject::READ_CSV);

    foreach ($file as $row) {
        list($animal, $class, $legs) = $row;
        printf("A %s is a %s with %d legs\n", $animal, $class, $legs);
    }

    ?>

Contents of animals.csv

    crocodile,reptile,4
    dolphin,mammal,0
    duck,bird,2
    koala,mammal,4
    salmon,fish,0

Вывод приведённого примера будет похож на:

    A crocodile is a reptile with 4 legs
    A dolphin is a mammal with 0 legs
    A duck is a bird with 2 legs
    A koala is a mammal with 4 legs
    A salmon is a fish with 0 legs

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

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

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