parse_ini_string()

¿Qué es la función parse_ini_string()?

La función parse_ini_string() analiza una cadena escrita en el formato de configuración INI y devuelve su contenido como un array asociativo. Es la versión en memoria de parse_ini_file(): en lugar de leer la configuración desde un archivo en disco, la lee desde una cadena que ya tienes en una variable.

Esto resulta útil cuando los datos de configuración llegan desde un origen distinto a un archivo local — una columna de base de datos, una respuesta HTTP, una variable de entorno o un here-doc embebido en el código. El formato INI en sí es el mismo que PHP usa para php.ini: pares clave = valor, cabeceras opcionales [sección] y comentarios con ;.

Esta página cubre la firma de la función, la salida con secciones frente a la plana, los tres modos de escáner y los problemas más comunes (palabras reservadas, caracteres especiales y fallos de análisis).

Sintaxis

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

La función devuelve un array asociativo en caso de éxito, o false en caso de fallo.

Ejemplo básico

Comienza con una cadena plana de pares clave = valor y lee los valores por clave:

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

La primera línea que empieza con ; es un comentario y se ignora. Cada una de las demás líneas se convierte en una entrada del array devuelto, con la clave correspondiente al nombre situado a la izquierda del =.

Agrupar valores por sección

Los archivos INI suelen organizar configuraciones relacionadas bajo cabeceras [sección]. Pasa true como segundo argumento para mantener esa estructura en el resultado — cada sección se convierte en un array anidado:

<?php

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

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

Salida:

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

)

Si $process_sections se deja en su valor por defecto false, la cabecera [settings] se descarta y se obtiene un array plano con name y email.

Modos de escáner

El tercer argumento controla cómo se interpretan los valores:

• INI_SCANNER_NORMAL (por defecto) — los valores se devuelven como cadenas y las constantes o palabras especiales se evalúan.
• INI_SCANNER_RAW — los valores se devuelven exactamente como están escritos, sin ninguna interpretación. Usa este modo para preservar cadenas literales.
• INI_SCANNER_TYPED — los booleanos, números y null se convierten a sus tipos nativos de PHP en lugar de cadenas.

INI_SCANNER_TYPED es el más útil para configuración real, ya que evita tener que convertir cadenas manualmente:

<?php

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

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

Salida:

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

En el modo normal, esos mismos valores serían todos cadenas ("1" para true, "3", "1.5").

Palabras reservadas y comillas

Algunos caracteres y palabras tienen un significado especial en el formato INI, así que hay que tener cuidado con lo siguiente:

• Las palabras true, false, on, off, yes, no, none y null se interpretan como booleanos/null en el modo tipado y como "1"/"" en el modo normal. Si necesitas el texto literal, encierra el valor entre comillas o usa INI_SCANNER_RAW.
• Los caracteres ?{}|&~!()^" están reservados y no deben usarse fuera de un valor entre comillas.
• Un valor que contenga espacios o caracteres especiales debe ir entre comillas: path = "C:\Program Files".

Gestión de fallos de análisis

parse_ini_string() devuelve false si la entrada no puede analizarse, por lo que conviene comprobar el resultado antes de usarlo:

<?php

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

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

Un valor en blanco no es un fallo — name = simplemente produce una cadena vacía para esa clave. Los fallos reales provienen de una sintaxis incorrecta, como un valor sin comillas que usa caracteres reservados.

Cuándo usarla

Recurre a parse_ini_string() cuando:

• El texto de configuración ya está en memoria (cargado desde una base de datos, una API o un stream) en lugar de estar en disco.
• Quieres un formato de configuración ligero y sin dependencias que personas no técnicas puedan editar.
• Necesitas validar o transformar contenido INI antes de persistirlo en un archivo.

Si la configuración se encuentra en un archivo real, usa parse_ini_file() en su lugar — lee y analiza en un solo paso. Para estructuras de datos más complejas, considera JSON mediante json_decode().

Conclusión

parse_ini_string() convierte una cadena en formato INI en un array de PHP, con agrupación opcional por secciones y tres modos de escáner para controlar cómo se tipan los valores. Usa $process_sections para preservar la estructura [sección], prefiere INI_SCANNER_TYPED cuando necesites booleanos y números reales, y comprueba siempre si se devuelve false cuando la entrada no es de confianza.

Práctica