(PHP 5 >= 5.3.0, PHP 7, PHP 8)
str_getcsv — Разбирает CSV-строку в массив
$string,$separator = ",",$enclosure = "\"",$escape = "\\"Функция разбирает входную строку по полям в формате CSV и возвращает массив c прочитанными полями.
Замечание: Функция учитывает региональный настройки. Поэтому функция иногда неправильно разбирает данные в отдельных однобайтовых кодировках, если значение константы
LC_CTYPEравноen_US.UTF-8.
stringСтрока для разбора.
separator
Параметр separator устанавливает
символ-разделитель полей и принимает только один однобайтовый символ.
enclosure
Параметр enclosure устанавливает
символ-ограничитель значения поля и принимает только один однобайтовый символ.
escape
Параметр escape устанавливает
символ экранирования и принимает только один однобайтовый символ или пустую строку.
Пустая строка "" отключает внутренний механизм экранирования.
Замечание: Обычно символ ограничителя значений —
enclosureэкранируется внутри поля путём удвоения; однако как альтернативу разрешается использовать символ экранированияescape. Поэтому для стандартных значений параметра смысл значений""и\"одинаков. Символ экранирования —escapeне несёт отдельного смысла, кроме экранирования символа ограничителя значений —enclosure; он даже не экранирует сам себя.
Начиная с 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 | Вместо строки с одним нулевым байтом возвращается пустая строка, если последнее поле содержит только незавершённый символ ограничения значения поля. enclosure. |
| 7.4.0 |
Функция теперь интерпретирует пустой параметр escape
как требование отключить внутренний механизм экранирования.
Раньше пустую строку функция рассматривала как значение по умолчанию для параметра.
|
Пример #1 Пример разбора CSV-строки в массив функцией str_getcsv()
<?php
$string = 'PHP,Java,Python,Kotlin,Swift';
$data = str_getcsv($string);
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);
var_dump($data);
?>Результат выполнения приведённого примера:
array(1) {
[0]=>
NULL
}