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

Назначение str_getcsv

str_getcsv: Разбирает CSV-строку в массив. Справочная сущность относится к разделу «Строки». Используйте её, когда это краткое назначение совпадает с задачей приложения; фактическое поведение подтверждайте сигнатурой и проверочным сценарием ниже.

Чем отличается str_getcsv

Это процедурная функция раздела «Строки». Её отличают имя str_getcsv, контракт «обязательные $string; необязательные $separator, $enclosure, $escape» и объявленный результат array; эти три признака нужно сверять вместе при выборе похожего API.

Смысловое направление str_getcsv

Смысловое направление str_getcsv — «декодирование или разбор». В прикладном коде не доверяйте структуре результата до отдельной проверки схемы. Контрольный набор для этой операции: проверьте повреждённый, обрезанный и неожиданный по типу ввод. Такой акцент отделяет str_getcsv от API с похожей сигнатурой, но противоположным действием или другим жизненным циклом.

Сигнатура str_getcsv

Структурная запись: array str_getcsv(string $string, string $separator = ",", string $enclosure = "\"", string $escape = "\\"). В ней 4 параметра: обязательные $string; необязательные $separator, $enclosure, $escape. Результат объявлен как array; перед переносом кода сопоставьте сигнатуру с версией PHP и составом расширений проекта.

Параметры str_getcsv

Порядок и роли аргументов по сигнатуре: 1. $string — string, обязателен; 2. $separator — string, необязателен, default ","; 3. $enclosure — string, необязателен, default "\""; 4. $escape — string, необязателен, default "\\".

Контроль входных данных для str_getcsv

1) string $string — обязательный: разведите пустую строку, штатное значение и ввод с неожиданной кодировкой или длиной. 2) string $separator — необязательный: разведите пустую строку, штатное значение и ввод с неожиданной кодировкой или длиной. 3) string $enclosure — необязательный: разведите пустую строку, штатное значение и ввод с неожиданной кодировкой или длиной. 4) string $escape — необязательный: разведите пустую строку, штатное значение и ввод с неожиданной кодировкой или длиной.

Результат str_getcsv

str_getcsv объявляет результат типа array. str_getcsv возвращает коллекцию типа array. Пустой набор может быть корректным результатом, поэтому его смысл определяют отдельно от исключения или диагностического сообщения.

Проверочный сценарий для str_getcsv

Убедитесь, что раздел «Строки» доступен в целевой сборке PHP. Сначала выполните контрольный вызов с обязательным набором string $string. Затем отдельно добавьте необязательные параметры string $separator=",", string $enclosure="\"", string $escape="\\", чтобы увидеть влияние значений по умолчанию. Для профиля «коллекции и обход» важно отличать пустую коллекцию от ошибки получения данных; негативный сценарий должен проверить пустой набор, один элемент и изменение коллекции во время обхода.

Интеграция str_getcsv в проект

Проверку доступности str_getcsv и преобразование входных значений разместите у границы модуля «Строки». Для профиля «коллекции и обход» вынесите обработку отказа в одну ветку и добавьте к журналу имя операции, версию PHP и безопасные метаданные входа. Не применяйте оператор @: он скрывает диагностический сигнал, необходимый для разбора сбоя. Повторный вызов разрешайте только после явной проверки, что операция str_getcsv не создаёт нежелательный повторный эффект в вашем сценарии.

Диагностика str_getcsv

Сначала запишите точную сигнатуру array str_getcsv(string $string, string $separator = ",", string $enclosure = "\"", string $escape = "\\") и фактические типы переданных значений. Затем подтвердите загрузку расширения «Строки» в той же среде, где выполняется str_getcsv. Если результат неожиданен, сравните его тип с array и воспроизведите вызов на минимальном входе без подавления предупреждений. После исправления повторите штатный и граничный сценарии, чтобы исключить маскировку ошибки случайным успешным результатом.

Границы применения

Для категории «коллекции и обход» применяйте отдельный негативный тест: проверить пустой набор, один элемент и изменение коллекции во время обхода. В production-коде важно отличать пустую коллекцию от ошибки получения данных. Исходные предупреждения и примечания не копируются на эту страницу: перед решением, влияющим на совместимость или безопасность, сверяйте поведение в целевой версии PHP.

Когда выбирать str_getcsv

Выбор str_getcsv оправдан, когда одновременно выполнены три условия: 1) в сборке доступно расширение «Строки»; 2) сигнатура содержит 4 аргумента: обязательных 1, необязательных 3; 3) вызывающему коду нужен результат array и действие «декодирование или разбор». Для профиля «коллекции и обход» до интеграции отдельно подтвердите применимость правила: «undefined». Если хотя бы один пункт не выполняется, сравните контракт с fputcsv: у него другое назначение, владелец или набор входных данных.

Сравнение str_getcsv с соседними API

Для str_getcsv базовый ориентир: разбирает csv-строку в массив; обязательные $string; необязательные $separator, $enclosure, $escape; результат array. Сопоставление с опубликованными соседями: fputcsv: формирует строку в csv-формате и записывает строку в файловый указатель; вход — обязательные $stream, $fields; необязательные $separator, $enclosure, $escape, $eol; результат — int|false. fgetcsv: получает строку из файлового указателя и разбирает по csv-полям; вход — обязательные $stream; необязательные $length, $separator, $enclosure, $escape; результат — array|false. SplFileObject::fgetcsv: получает строку из файлового указателя и разбирает по csv-полям; вход — необязательные $separator, $enclosure, $escape; результат — array|false. Выбор делайте по различиям владельца, контракта и жизненного цикла, а не по сходству имени.

Версии и ограничения

В структурной истории исходной записи отмечены версии: 8.4.0, 7.4.0. str_getcsv сверена по закреплённой ревизии php/doc-ru. Перед обновлением PHP повторите тесты типов, предупреждений и граничных значений для этой сущности. Не переносите выводы между версиями без повторного запуска минимального воспроизводимого примера для str_getcsv.

Связанные материалы