parse_ini_string()

What Is the parse_ini_string() Function?

The parse_ini_string() function parses a string written in the INI configuration format and returns its contents as an associative array. It is the in-memory companion to parse_ini_file(): instead of reading settings from a file on disk, it reads them from a string you already hold in a variable.

This is useful when configuration data arrives from somewhere other than a local file — a database column, an HTTP response, an environment variable, or a here-doc embedded in your code. The INI format itself is the same one PHP uses for php.ini: key = value pairs, optional [section] headers, and ; comments.

This page covers the function signature, sectioned vs. flat output, the three scanner modes, and the most common gotchas (reserved words, special characters, and parse failures).

Syntax

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

The function returns an associative array on success, or false on failure.

Basic Example

Start with a flat string of key = value pairs and read the values back by key:

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

The leading line starting with ; is a comment and is ignored. Every other line becomes one entry in the returned array, keyed by the name to the left of the =.

Grouping Values by Section

INI files often organize related settings under [section] headers. Pass true as the second argument to keep that structure in the result — each section becomes a nested array:

<?php

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

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

Output:

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

)

With $process_sections left at its default false, the [settings] header is dropped and you get a single flat array of name and email.

Scanner Modes

The third argument controls how values are interpreted:

• INI_SCANNER_NORMAL (default) — values come back as strings, and constants/special words are evaluated.
• INI_SCANNER_RAW — values are returned exactly as written, with no interpretation. Use this to preserve literal strings.
• INI_SCANNER_TYPED — booleans, numbers, and null are converted to their native PHP types instead of strings.

INI_SCANNER_TYPED is the most useful for real configuration, because it saves you from casting strings by hand:

<?php

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

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

Output:

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

In normal mode those same values would all be strings ("1" for true, "3", "1.5").

Reserved Words and Quoting

A few characters and words have special meaning in the INI format, so watch out for these:

• The words true, false, on, off, yes, no, none, and null are interpreted as booleans/null in typed mode and as "1"/"" in normal mode. If you need the literal text, wrap the value in quotes or use INI_SCANNER_RAW.
• The characters ?{}|&~!()^" are reserved and must not be used outside a quoted value.
• A value that contains spaces or special characters should be quoted: path = "C:\Program Files".

Handling Parse Failures

parse_ini_string() returns false if the input cannot be parsed, so guard the result before using it:

<?php

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

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

A blank value is not a failure — name = simply yields an empty string for that key. Real failures come from malformed syntax, such as an unquoted value that uses reserved characters.

When to Use It

Reach for parse_ini_string() when:

• Configuration text is already in memory (loaded from a DB, an API, or a stream) rather than on disk.
• You want a lightweight, dependency-free config format that non-developers can edit.
• You need to validate or transform INI content before persisting it to a file.

If the configuration lives in an actual file, use parse_ini_file() instead — it reads and parses in one step. For richer data structures, consider JSON via json_decode().

Conclusion

parse_ini_string() turns an INI-formatted string into a PHP array, with optional section grouping and three scanner modes for controlling how values are typed. Use $process_sections to preserve [section] structure, prefer INI_SCANNER_TYPED when you want real booleans and numbers, and always check for a false return when the input is untrusted.

Practice