parse_ini_file()

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

La función parse_ini_file() es una función integrada de PHP que lee un archivo de configuración escrito en formato INI y devuelve sus ajustes como un array asociativo. INI es el sencillo formato clave = valor que usa el propio php.ini, y es una opción popular para almacenar ajustes de la aplicación (credenciales de base de datos, indicadores de características, claves API) fuera del código.

Esta página explica la sintaxis, cómo se tipifican los valores INI, cómo funcionan las secciones, los modos del analizador y los problemas a tener en cuenta (palabras reservadas, manejo de errores) antes de usarla en producción.

Aquí está la sintaxis básica de la función parse_ini_file():

La sintaxis PHP de parse_ini_file()

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

Los parámetros son:

• $filename — ruta al archivo INI que se va a analizar.
• $process_sections (opcional) — cuando es true, el resultado es un array multidimensional indexado por los nombres de [sección] del archivo. Por defecto es false, que aplana todas las claves en un único array.
• $scanner_mode (opcional) — controla cómo se interpretan los valores. Puede ser:
  • INI_SCANNER_NORMAL (por defecto) — los valores se devuelven como strings; true/on/yes se convierten en "1" y false/off/no se convierten en "".
  • INI_SCANNER_RAW — los valores se toman de forma literal; sin interpolación de ${...} ni constantes.
  • INI_SCANNER_TYPED — los booleanos, enteros y null conservan sus tipos PHP nativos (véase más abajo).

La función devuelve un array en caso de éxito, o false en caso de error (por ejemplo, si el archivo no existe), así que comprueba siempre el resultado antes de usarlo.

Cómo usar la función parse_ini_file()

Comienza con un archivo de configuración en formato INI. Los comentarios empiezan con punto y coma (;):

config.ini

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

Luego analízalo y lee los valores por clave:

Lectura de un archivo INI plano

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

La comprobación === false es importante: parse_ini_file() devuelve false en caso de error (archivo no encontrado, ruta no legible), y tratar ese valor como un array produciría advertencias.

Agrupación de ajustes con secciones

Los archivos de configuración reales suelen dividirse en [secciones]. Pasa true como segundo argumento para mantener esa estructura como un array anidado:

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

Con $process_sections establecido en true, cada sección se convierte en un subarray. Esto evita que claves con el mismo nombre (por ejemplo, un host común en dos secciones) se sobreescriban mutuamente.

Cómo se tipifican los valores (modos del analizador)

Por defecto, cada valor se devuelve como un string — los booleanos se convierten en "1" o en una cadena vacía "", y los números permanecen como texto:

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

Si quieres tipos PHP nativos, usa 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)

Este es el modo más seguro cuando el código depende de booleanos reales (if ($c['enabled'])) en lugar de cadenas con valor verdadero — ten en cuenta que la cadena "0" y la cadena vacía se evalúan como falsy, pero "false" analizado en modo NORMAL sería truthy, lo que es una fuente frecuente de errores.

Palabras reservadas y precauciones

Algunos caracteres y palabras tienen un significado especial en los archivos INI y pueden causar sorpresas:

• Valores reservados: null, yes, no, true, false, on, off, none se interpretan. Para mantenerlos como literales, pon el valor entre comillas: mode = "off".
• Caracteres reservados: ?{}|&~!()^" no deben usarse en un valor sin comillas.
• Las claves denominadas null, yes, no, true, false, on, off, none no están permitidas como claves.
• El ; inicia un comentario, por lo que un valor que contenga un punto y coma debe ir entre comillas.

Para archivos no confiables o subidos por usuarios, se prefiere el más seguro parse_ini_string() después de leer el archivo con file_get_contents(), o valida la ruta primero — nunca analices rutas arbitrarias proporcionadas por el usuario.

Cuándo usar parse_ini_file()

parse_ini_file() es una buena opción cuando quieres un archivo de configuración editable por humanos que no desarrolladores puedan ajustar, y cuando los datos son ajustes superficiales de clave/valor. Para datos profundamente anidados o con muchos arrays, JSON (json_decode()) o arrays PHP devueltos desde un archivo incluido con require suelen ser una mejor elección. Consulta PHP File Handling para el conjunto más amplio de funciones de archivos, y PHP Constants ya que los valores INI pueden hacer referencia a constantes definidas en el modo INI_SCANNER_NORMAL.

Conclusión

La función parse_ini_file() convierte un archivo de configuración INI en un array PHP con una sola llamada. Recuerda las tres cosas que suelen causar problemas: comprueba si el resultado es false, pasa true para $process_sections cuando el archivo usa [secciones], y usa INI_SCANNER_TYPED cuando necesites booleanos e enteros reales en lugar de strings.

Práctica