Разбирает CSV-строку в массив

# str_getcsv

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

str_getcsv — Разбирает CSV-строку в массив

### Описание

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` экранируется внутри поля путём удвоения; однако как альтернативу разрешается использовать символ экранирования `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, 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-полей

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open