parse_ini_file()

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

Функция parse_ini_file() — это встроенная функция PHP, которая читает конфигурационный файл в формате INI и возвращает его настройки в виде ассоциативного массива. INI — это простой формат ключ = значение, используемый самим php.ini, и он является популярным способом хранения настроек приложения (учётные данные для базы данных, флаги функций, API-ключи) вне исходного кода.

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

Вот базовый синтаксис функции parse_ini_file():

Синтаксис parse_ini_file() в PHP

parse_ini_file(string $filename, bool $process_sections = false, int $scanner_mode = INI_SCANNER_NORMAL): array|false

Параметры:

• $filename — путь к INI-файлу для парсинга.
• $process_sections (необязательный) — если true, результат представляет собой многомерный массив с ключами, соответствующими именам [секций] в файле. По умолчанию false, что объединяет все ключи в один массив.
• $scanner_mode (необязательный) — управляет интерпретацией значений. Одно из:
  • INI_SCANNER_NORMAL (по умолчанию) — значения возвращаются как строки; true/on/yes превращаются в "1", а false/off/no — в "".
  • INI_SCANNER_RAW — значения берутся дословно; интерполяция ${...} и констант не выполняется.
  • INI_SCANNER_TYPED — булевы значения, целые числа и null сохраняют свои нативные типы PHP (см. ниже).

Функция возвращает массив при успехе или false при ошибке (например, если файл не существует), поэтому всегда проверяйте результат перед использованием.

Как использовать функцию parse_ini_file()

Начните с конфигурационного файла в формате INI. Комментарии начинаются с точки с запятой (;):

config.ini

; Example configuration file
name = John Doe
email = [email protected]
phone = 555-555-5555

Затем выполните парсинг и прочитайте значения по ключу:

Чтение плоского INI-файла

<?php

$config = parse_ini_file('config.ini');

if ($config === false) {
    echo "Failed to parse config.ini";
} else {
    echo $config['name'];  // John Doe
    echo $config['email']; // [email protected]
    echo $config['phone']; // 555-555-5555
}

Проверка === false важна: parse_ini_file() возвращает false при ошибке (отсутствующий файл, нечитаемый путь), и обращение к нему как к массиву вызовет предупреждения.

Группировка настроек с помощью секций

Реальные конфигурационные файлы обычно разбиты на [секции]. Передайте true в качестве второго аргумента, чтобы сохранить эту структуру в виде вложенного массива:

database.ini

[database]
host = localhost
port = 3306

[app]
name = "My App"
debug = true

<?php

$config = parse_ini_file('database.ini', true);

echo $config['database']['host']; // localhost
echo $config['database']['port']; // 3306
echo $config['app']['name'];      // My App

При $process_sections равном true каждая секция становится подмассивом. Это предотвращает перезапись ключей с одинаковыми именами (например, host в двух секциях).

Типизация значений (режимы сканирования)

По умолчанию каждое значение возвращается как строка — булевы значения преобразуются в "1" или пустую строку "", а числа остаются текстовыми:

<?php
// enabled = true, count = 42 in the INI file
$c = parse_ini_file('app.ini');
var_dump($c['enabled']); // string(1) "1"
var_dump($c['count']);   // string(2) "42"

Если нужны нативные типы PHP, используйте INI_SCANNER_TYPED:

<?php
$c = parse_ini_file('app.ini', false, INI_SCANNER_TYPED);
var_dump($c['enabled']); // bool(true)
var_dump($c['count']);   // int(42)

Это наиболее безопасный режим, когда код опирается на настоящие булевы значения (if ($c['enabled'])), а не на строки с истинным значением — обратите внимание, что строка "0" и пустая строка оцениваются как ложные, но "false", разобранное в режиме NORMAL, было бы истинным, что является частым источником ошибок.

Зарезервированные слова и подводные камни

Некоторые символы и слова имеют особое значение в INI-файлах и могут вызвать неожиданное поведение:

• Зарезервированные значения: null, yes, no, true, false, on, off, none интерпретируются особым образом. Чтобы использовать их буквально, заключите значение в кавычки: mode = "off".
• Зарезервированные символы: ?{}|&~!()^" нельзя использовать в неэкранированном значении.
• Ключи с именами null, yes, no, true, false, on, off, none не допускаются.
• Символ ; начинает комментарий, поэтому значение, содержащее точку с запятой, должно быть заключено в кавычки.

Для ненадёжных или загружаемых пользователями файлов предпочтительнее использовать parse_ini_string() после чтения файла с помощью file_get_contents() или предварительно проверять путь — никогда не выполняйте парсинг произвольных путей, указанных пользователем.

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

parse_ini_file() хорошо подходит, когда нужен конфигурационный файл, доступный для редактирования людьми, в том числе не разработчиками, и когда данные представляют собой простые настройки в формате ключ/значение. Для глубоко вложенных или массивоёмких данных обычно лучше подходят JSON (json_decode()) или PHP-массивы, возвращаемые из подключаемого через require файла. Смотрите PHP File Handling для полного набора файловых функций, а также PHP Constants, поскольку значения INI могут ссылаться на определённые константы в режиме INI_SCANNER_NORMAL.

Заключение

Функция parse_ini_file() превращает INI-конфигурационный файл в PHP-массив за один вызов. Помните три вещи, на которых чаще всего спотыкаются: проверяйте возврат значения false, передавайте true для $process_sections, если файл использует [секции], и используйте INI_SCANNER_TYPED, когда нужны настоящие булевы значения и целые числа вместо строк.

Практика