parse_ini_file()

Qu'est-ce que la fonction parse_ini_file() ?

La fonction parse_ini_file() est une fonction PHP intégrée qui lit un fichier de configuration écrit au format INI et retourne ses paramètres sous forme de tableau associatif. Le format INI est le simple format clé = valeur utilisé par php.ini lui-même, et c'est un choix populaire pour stocker les paramètres d'une application (identifiants de base de données, drapeaux de fonctionnalités, clés API) en dehors de votre code.

Cette page explique la syntaxe, comment les valeurs INI sont typées, comment fonctionnent les sections, les modes de scanner, ainsi que les pièges (mots réservés, gestion des erreurs) à connaître avant de l'utiliser en production.

Voici la syntaxe de base de la fonction parse_ini_file() :

La syntaxe PHP de parse_ini_file()

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

Les paramètres sont :

• $filename — chemin vers le fichier INI à analyser.
• $process_sections (optionnel) — lorsque true, le résultat est un tableau multidimensionnel dont les clés correspondent aux noms [section] du fichier. La valeur par défaut est false, ce qui aplatit toutes les clés dans un seul tableau.
• $scanner_mode (optionnel) — contrôle la façon dont les valeurs sont interprétées. L'une des valeurs suivantes :
  • INI_SCANNER_NORMAL (par défaut) — les valeurs sont retournées sous forme de chaînes ; true/on/yes deviennent "1" et false/off/no deviennent "".
  • INI_SCANNER_RAW — les valeurs sont prises telles quelles ; pas d'interpolation de ${...} ni de constantes.
  • INI_SCANNER_TYPED — les booléens, entiers et null conservent leurs types PHP natifs (voir ci-dessous).

La fonction retourne un tableau en cas de succès, ou false en cas d'échec (par exemple, si le fichier n'existe pas) — vérifiez toujours le résultat avant de l'utiliser.

Comment utiliser la fonction parse_ini_file() ?

Commencez avec un fichier de configuration au format INI. Les commentaires commencent par un point-virgule (;) :

config.ini

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

Ensuite, analysez-le et lisez les valeurs par clé :

Lecture d'un fichier INI plat

<?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 vérification === false est importante : parse_ini_file() retourne false en cas d'échec (fichier manquant, chemin illisible), et traiter ce résultat comme un tableau déclencherait des avertissements.

Regrouper les paramètres avec des sections

Les vrais fichiers de configuration sont généralement divisés en [sections]. Passez true comme second argument pour conserver cette structure sous forme de tableau imbriqué :

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

Avec $process_sections défini sur true, chaque section devient un sous-tableau. Cela évite que des clés portant le même nom (par exemple un host commun dans deux sections) ne s'écrasent mutuellement.

Comment les valeurs sont typées (modes de scanner)

Par défaut, chaque valeur est retournée sous forme de chaîne — les booléens sont convertis en "1" ou en chaîne vide "", et les nombres restent textuels :

<?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 vous souhaitez des types PHP natifs, utilisez 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)

C'est le mode le plus sûr lorsque votre code repose sur de vrais booléens (if ($c['enabled'])) plutôt que sur des chaînes à valeur vrai — notez que la chaîne "0" et la chaîne vide sont toutes deux falsy, mais "false" analysé en mode NORMAL serait truthy, ce qui est une source fréquente de bugs.

Mots réservés et pièges

Quelques caractères et mots ont une signification particulière dans les fichiers INI et peuvent provoquer des surprises :

• Valeurs réservées : null, yes, no, true, false, on, off, none sont interprétées. Pour les conserver telles quelles, entourez la valeur de guillemets : mode = "off".
• Caractères réservés : ?{}|&~!()^" ne doivent pas être utilisés dans une valeur non entourée de guillemets.
• Les clés nommées null, yes, no, true, false, on, off, none ne sont pas autorisées comme clés.
• Le ; démarre un commentaire, donc une valeur contenant un point-virgule doit être entourée de guillemets.

Pour les fichiers non fiables ou téléversés par des utilisateurs, préférez le plus sûr parse_ini_string() après avoir lu le fichier avec file_get_contents(), ou validez d'abord le chemin — n'analysez jamais des chemins arbitraires fournis par l'utilisateur.

Quand utiliser parse_ini_file() ?

parse_ini_file() est un bon choix lorsque vous voulez un fichier de configuration éditable par des humains que des non-développeurs peuvent modifier, et lorsque les données sont des paramètres clé/valeur simples. Pour des données profondément imbriquées ou nécessitant beaucoup de tableaux, JSON (json_decode()) ou des tableaux PHP retournés par un fichier required sont généralement un meilleur choix. Consultez PHP File Handling pour l'ensemble des fonctions de fichiers, et PHP Constants car les valeurs INI peuvent référencer des constantes définies en mode INI_SCANNER_NORMAL.

Conclusion

La fonction parse_ini_file() transforme un fichier de configuration INI en tableau PHP en un seul appel. Retenez les trois points qui font trébucher les développeurs : vérifiez un retour false, passez true pour $process_sections lorsque votre fichier utilise des [sections], et utilisez INI_SCANNER_TYPED quand vous avez besoin de vrais booléens et entiers plutôt que de chaînes.

Pratique