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

fgetcsv

(PHP 4, PHP 5, PHP 7, PHP 8)

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

Описание

function fgetcsv(
    resource $stream,
    ?int $length = null,
    string $separator = ",",
    string $enclosure = "\"",
    string $escape = "\\"
): array|false

Функция fgetcsv() аналогична функции fgets(), но разбирает прочитанную строку на поля в формате CSV, которые возвращает в массиве.

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

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

stream

Корректный файловый указатель, который открыли функцией fopen(), popen() или fsockopen().

length

Параметру устанавливают значение, которое превышает размер самой длинной строки CSV-файла в байтах с учётом символов конца строки, иначе строка разобьётся на части по length байтов; длина значений внутри символов-ограничителей не учитывается.

Функция снимет ограничение на длину строки, но замедлит работу, если параметр пропустили или начиная с PHP 8.0.0 установили для параметра значение 0 или null.

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

Внимание

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

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

При успешном выполнении функция возвращает индексный массив с прочитанными полями или false, если возникла ошибка.

Замечание:
Пустую строку в CSV-файле функция интерпретирует не как ошибку, а как одно поле со значением null, которое возвращается в одноэлементном массиве.

Замечание:
Включение опции auto_detect_line_endings во время выполнения иногда помогает исправить неправильное распознавание языком PHP концов строк при чтении файлов на Macintosh-совместимом компьютере или файлов, которые создали на Макинтоше.

Ошибки

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

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

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

Версия	Описание
8.4.0	Вызов функции без явной передачи аргумента `escape` устарел.
8.3.0	Для последнего поля, которое состоит из единственного незакрытого символа-ограничителя, вместо строки с одним нулевым байтом теперь возвращается пустая строка.
8.0.0	Параметр `length` теперь принимает значение `null`.
7.4.0	Параметр `escape` теперь также принимает пустую строку для отключения встроенного механизма экранирования.

Примеры

Пример #1 Пример считывания и вывода содержимого CSV-файла

<?php

if (($handle = fopen("test.csv", "r")) !== false) {
    $row = 1;

    while (($fields = fgetcsv($handle, 1000, ",", "\"", "\\")) !== false) {
        $num = count($fields);

        echo "\n<p>Строка: $row. Количество полей: $num. Значения:</p>\n<ol>";

        for ($c = 0; $c < $num; $c++) {
            echo "\n\t<li>", $fields[$c], "</li>";
        }

        echo "\n</ol>";

        $row++;
    }

    fclose($handle);
}

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

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