parse_ini_file()

What is the parse_ini_file() Function?

The parse_ini_file() function is a built-in PHP function that reads a configuration file written in the INI format and returns its settings as an associative array. INI is the simple key = value format used by php.ini itself, and it is a popular choice for storing app settings (database credentials, feature flags, API keys) outside of your code.

This page explains the syntax, how INI values are typed, how sections work, the scanner modes, and the gotchas (reserved words, error handling) you need to know before using it in production.

Here is the basic syntax of the parse_ini_file() function:

The PHP syntax of parse_ini_file()

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

The parameters are:

• $filename — path to the INI file to parse.
• $process_sections (optional) — when true, the result is a multidimensional array keyed by the [section] names in the file. Defaults to false, which flattens every key into one array.
• $scanner_mode (optional) — controls how values are interpreted. One of:
  • INI_SCANNER_NORMAL (default) — values come back as strings; true/on/yes become "1" and false/off/no become "".
  • INI_SCANNER_RAW — values are taken verbatim; no interpolation of ${...} or constants.
  • INI_SCANNER_TYPED — booleans, integers and null keep their native PHP types (see below).

The function returns an array on success, or false on failure (for example, the file does not exist), so always check the result before using it.

How to Use the parse_ini_file() Function

Start with a configuration file in INI format. Comments begin with a semicolon (;):

config.ini

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

Then parse it and read the values by key:

Reading a flat INI file

<?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
}

The === false check matters: parse_ini_file() returns false on failure (missing file, unreadable path), and treating that as an array would trigger warnings.

Grouping Settings with Sections

Real config files are usually split into [sections]. Pass true as the second argument to keep that structure as a nested array:

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

With $process_sections set to true, each section becomes a sub-array. This keeps keys with the same name (a common host in two sections, say) from overwriting each other.

How Values Are Typed (Scanner Modes)

By default every value is returned as a string — booleans are converted to "1" or an empty string "", and numbers stay textual:

<?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"

If you want native PHP types, use 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)

This is the safest mode when your code relies on real booleans (if ($c['enabled'])) rather than truthy strings — note that the string "0" and the empty string both evaluate as falsy, but "false" parsed in NORMAL mode would be truthy, which is a frequent source of bugs.

Reserved Words and Gotchas

A few characters and words have special meaning in INI files and will cause surprises:

• Reserved values: null, yes, no, true, false, on, off, none are interpreted. To keep them literal, wrap the value in quotes: mode = "off".
• Reserved characters: ?{}|&~!()^" must not be used in an unquoted value.
• Keys named null, yes, no, true, false, on, off, none are not allowed as keys.
• The ; starts a comment, so a value containing a semicolon must be quoted.

For untrusted or user-uploaded files, prefer the safer parse_ini_string() after reading the file with file_get_contents(), or validate the path first — never parse arbitrary user-supplied paths.

When to Use parse_ini_file()

parse_ini_file() is a good fit when you want a human-editable config file that non-developers can tweak, and when the data is shallow key/value settings. For deeply nested or array-heavy data, JSON (json_decode()) or PHP arrays returned from a required file are usually a better choice. See PHP File Handling for the broader set of file functions, and PHP Constants since INI values can reference defined constants in INI_SCANNER_NORMAL mode.

Conclusion

The parse_ini_file() function turns an INI configuration file into a PHP array in one call. Remember the three things that trip people up: check for a false return, pass true for $process_sections when your file uses [sections], and use INI_SCANNER_TYPED when you need real booleans and integers instead of strings.

Practice