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

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

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

＋Добавить

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

down

android991 at gmail dot com ¶

7 years ago

Be aware.
There is bug 46569 persists that breaks usage of SplFileObject::fgetcsv() after SplFileObject::seek()-ing to a non-zero position and then returns the contents of wrong line - off by one
<?php
$file = new SplFileObject('foo/bar.csv');
$file->seek(1);
print_r($file->fgetcsv()); // reads 3rd line against 2nd

down

InvisibleSmiley ¶

4 years ago

Not that this may return NULL instead of FALSE depending on the given SplFileObject flags in versions prior to PHP 8.1.

Change: https://github.com/php/php-src/commit/188b1d4c7c7b3482584e248522d94e06ba616a1c

Testcase: https://3v4l.org/6dQTT

down

Denitz ¶

7 years ago

If your CSV doesn't have enclosures, you can face an issue with default " identified as enclosure in data. Empty $enclosure is not allowed, but you can use same $enclosure as $delimiter (\n by default) to emulate empty enclosure.

down

v-fpiris at teknober dot com ¶

15 years ago

after setting the delimiter '\t' fgetcsv() truncates the value when it is empty string 

workaround:

<?php
$file = new SplFileObject($path);
$file->setFlags(SplFileObject::DROP_NEW_LINE);
while ($file->valid()) {
    $line = $file->fgets();
    $line = explode("\t", $line);

    print_r($line);
}
?>

down

vaughn dot clayton+php at servicetrade dot com ¶

13 years ago

Note that due to bugs 55807 and 61032, introduced in 5.3.8, if the csv in example #2 has a newline character at the end of each line, the foreach will execute 6 times.

The last time through the loop $row will be bool(false). This is true even if using SplFileObject::SKIP_EMPTY and SplFileObject::DROP_NEW_LINE.

Until the bug is fixed, the workaround is to also add SplFileObject::READ_AHEAD to your setFlags() call.

down

jbrauer ¶

6 years ago

Also while the enclosure character cannot be NULL you can set it to ASCII NUL character chr(0) with the same practical effect.

＋Добавить