PHP: str_getcsv

Описание

function str_getcsv(
    string $string,
    string $separator = ",",
    string $enclosure = "\"",
    string $escape = "\\"
): array

Функция разбирает входную строку по полям в формате CSV и возвращает массив c прочитанными полями.

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

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

string: Строка для разбора.
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.

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

Функция возвращает индексный массив, который содержит прочитанные поля.

Ошибки

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

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

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

Версия	Описание
8.4.0	Вызов функции без явной передачи аргумента `escape` устарел.
8.4.0	Функция теперь подражает поведению функций fgetcsv() и fputcsv() и выбрасывает ошибку ValueError, если в параметры `separator`, `enclosure` или `escape` передали недопустимое значение.
8.3.0	Для последнего поля, которое состоит из единственного незакрытого символа-ограничителя, вместо строки с одним нулевым байтом теперь возвращается пустая строка.
7.4.0	Функция теперь интерпретирует пустой параметр `escape` как требование отключить внутренний механизм экранирования. Раньше пустую строку функция рассматривала как значение по умолчанию для параметра.

Примеры

Пример #1 Пример разбора CSV-строки в массив функцией str_getcsv()

<?php

$string = 'PHP,Java,Python,Kotlin,Swift';
$data = str_getcsv($string, escape: '\\');

var_dump($data);

?>

Результат выполнения приведённого примера:

array(5) {
  [0]=>
  string(3) "PHP"
  [1]=>
  string(4) "Java"
  [2]=>
  string(6) "Python"
  [3]=>
  string(6) "Kotlin"
  [4]=>
  string(5) "Swift"
}

Пример #2 Пример работы функции str_getcsv() с пустой строкой

Предостережение

Для пустой строки функция вместо пустого массива возвращает значение [null].

<?php

$string = '';
$data = str_getcsv($string, escape: '\\');

var_dump($data);

?>

Результат выполнения приведённого примера:

array(1) {
  [0]=>
  NULL
}

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

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