parse_ini_string()

Что такое функция parse_ini_string()?

Функция parse_ini_string() разбирает строку, написанную в формате конфигурации INI, и возвращает её содержимое в виде ассоциативного массива. Это аналог parse_ini_file(), работающий в памяти: вместо чтения настроек из файла на диске она читает их из строки, уже находящейся в переменной.

Это удобно, когда конфигурационные данные поступают не из локального файла, а из другого источника — столбца базы данных, HTTP-ответа, переменной окружения или heredoc-блока, встроенного в код. Сам формат INI — тот же, что PHP использует для php.ini: пары key = value, необязательные заголовки [section] и комментарии с ;.

На этой странице рассматриваются сигнатура функции, вывод с секциями и без них, три режима сканера, а также наиболее распространённые подводные камни (зарезервированные слова, специальные символы и ошибки разбора).

Синтаксис

parse_ini_string(
    string $ini_string,
    bool $process_sections = false,
    int $scanner_mode = INI_SCANNER_NORMAL
): array|false

Функция возвращает ассоциативный массив при успехе или false при ошибке.

Базовый пример

Начните с плоской строки пар key = value и прочитайте значения по ключу:

<?php

$config = parse_ini_string(
    "; Example configuration string\n" .
    "name = John Doe\n" .
    "email = [email protected]\n" .
    "phone = 555-555-5555"
);

echo $config['name'];  // John Doe
echo $config['email']; // [email protected]
echo $config['phone']; // 555-555-5555

Первая строка, начинающаяся с ;, является комментарием и игнорируется. Каждая последующая строка становится одной записью в возвращаемом массиве с ключом, равным имени слева от =.

Группировка значений по секциям

В INI-файлах связанные настройки часто группируются под заголовками [section]. Передайте true вторым аргументом, чтобы сохранить эту структуру в результате — каждая секция становится вложенным массивом:

<?php

$ini = "[settings]\nname = John Doe\nemail = [email protected]";

$config = parse_ini_string($ini, true);
print_r($config);

Вывод:

Array
(
    [settings] => Array
        (
            [name] => John Doe
            [email] => [email protected]
        )

)

Если $process_sections оставить со значением по умолчанию false, заголовок [settings] отбрасывается и вы получаете единый плоский массив с name и email.

Режимы сканера

Третий аргумент управляет интерпретацией значений:

• INI_SCANNER_NORMAL (по умолчанию) — значения возвращаются как строки, константы и специальные слова вычисляются.
• INI_SCANNER_RAW — значения возвращаются точно в том виде, в каком они записаны, без интерпретации. Используйте этот режим для сохранения литеральных строк.
• INI_SCANNER_TYPED — булевы значения, числа и null преобразуются в их родные PHP-типы вместо строк.

INI_SCANNER_TYPED наиболее полезен для реальной конфигурации, так как избавляет от ручного приведения строк к типам:

<?php

$ini = "debug = true\nretries = 3\ntimeout = 1.5";

$config = parse_ini_string($ini, false, INI_SCANNER_TYPED);
var_dump($config);

Вывод:

array(3) {
  ["debug"]=>
  bool(true)
  ["retries"]=>
  int(3)
  ["timeout"]=>
  float(1.5)
}

В обычном режиме те же самые значения были бы строками ("1" для true, "3", "1.5").

Зарезервированные слова и кавычки

Несколько символов и слов имеют специальное значение в формате INI, поэтому обратите внимание на следующее:

• Слова true, false, on, off, yes, no, none и null интерпретируются как булевы значения/null в типизированном режиме и как "1"/"" в обычном режиме. Если вам нужен буквальный текст, оберните значение в кавычки или используйте INI_SCANNER_RAW.
• Символы ?{}|&~!()^" зарезервированы и не должны использоваться вне значения в кавычках.
• Значение, содержащее пробелы или специальные символы, должно быть заключено в кавычки: path = "C:\Program Files".

Обработка ошибок разбора

parse_ini_string() возвращает false, если входные данные не удаётся разобрать, поэтому проверяйте результат перед использованием:

<?php

$config = parse_ini_string($_POST['config'] ?? '', true);

if ($config === false) {
    echo 'Invalid configuration string.';
} else {
    // safe to use $config here
    print_r($config);
}

Пустое значение не является ошибкой — name = просто даёт пустую строку для этого ключа. Настоящие ошибки возникают из-за неверного синтаксиса, например незакавыченного значения, содержащего зарезервированные символы.

Когда использовать

Используйте parse_ini_string() когда:

• Конфигурационный текст уже находится в памяти (загружен из БД, API или потока), а не на диске.
• Нужен лёгкий, независимый от дополнительных зависимостей формат конфигурации, который могут редактировать не-разработчики.
• Необходимо проверить или преобразовать содержимое INI перед сохранением его в файл.

Если конфигурация находится в реальном файле, используйте вместо этого parse_ini_file() — он читает и разбирает за один шаг. Для более богатых структур данных рассмотрите JSON через json_decode().

Заключение

parse_ini_string() преобразует строку в формате INI в массив PHP с необязательной группировкой по секциям и тремя режимами сканера для управления типизацией значений. Используйте $process_sections для сохранения структуры [section], предпочитайте INI_SCANNER_TYPED, когда нужны настоящие булевы значения и числа, и всегда проверяйте возврат false, если входные данные ненадёжны.

Практика