fgetcsv

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

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

Описание

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

Функция похожа на функцию fgets(), за исключением того, что функция fgetcsv() анализирует строку на наличие полей в формате 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 экранируется внутри поля путём удвоения; однако, разрешается указывать символ экранирования escape как альтернативу. Поэтому значения по умолчанию этих параметров "" и \" имеют одинаковое значение. Кроме разрешения экранировать символ ограничителя enclosure символ экранирования escape не имеет особого смысла; он даже не предназначен для самого экранирования.

Внимание

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

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

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

Замечание:

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

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

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

Версия Описание
8.0.0 Теперь параметр length принимает значение null.
7.4.0 Теперь параметр escape умеет принимать пустую строку для отключения встроенного механизма экранирования.

Примеры

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

<?php

$row
= 1;

if ((
$handle = fopen("test.csv", "r")) !== FALSE) {
while ((
$data = fgetcsv($handle, 1000, ",")) !== FALSE) {
$num = count($data);
echo
"<p> $num полей в строке $row: <br /></p>\n";
$row++;

for (
$c=0; $c < $num; $c++) {
echo
$data[$c] . "<br />\n";
}
}

fclose($handle);
}

?>

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

  • str_getcsv() - Разбирает CSV-строку в массив
  • explode() - Разбивает строку разделителем
  • file() - Читает содержимое файла и помещает его в массив
  • pack() - Упаковывает данные в двоичную строку
  • fputcsv() - Формирует строку в CSV-формате и записывает строку в файловый указатель