parse_ini_file()

Was ist die parse_ini_file()-Funktion?

Die parse_ini_file()-Funktion ist eine eingebaute PHP-Funktion, die eine Konfigurationsdatei im INI-Format einliest und deren Einstellungen als assoziatives Array zurückgibt. INI ist das einfache key = value-Format, das auch von php.ini selbst verwendet wird, und es ist eine beliebte Wahl zum Speichern von App-Einstellungen (Datenbank-Zugangsdaten, Feature-Flags, API-Keys) außerhalb des Codes.

Diese Seite erklärt die Syntax, wie INI-Werte typisiert werden, wie Abschnitte funktionieren, die Scanner-Modi und die Fallstricke (reservierte Wörter, Fehlerbehandlung), die Sie kennen müssen, bevor Sie die Funktion in der Produktion einsetzen.

Hier ist die grundlegende Syntax der parse_ini_file()-Funktion:

Die PHP-Syntax von parse_ini_file()

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

Die Parameter sind:

• $filename — Pfad zur zu parsenden INI-Datei.
• $process_sections (optional) — wenn true, ist das Ergebnis ein mehrdimensionales Array, das nach den [section]-Namen in der Datei gegliedert ist. Standardmäßig false, was alle Schlüssel in ein einziges Array zusammenführt.
• $scanner_mode (optional) — steuert, wie Werte interpretiert werden. Einer von:
  • INI_SCANNER_NORMAL (Standard) — Werte werden als Strings zurückgegeben; true/on/yes werden zu "1" und false/off/no werden zu "".
  • INI_SCANNER_RAW — Werte werden wörtlich übernommen; keine Interpolation von ${...} oder Konstanten.
  • INI_SCANNER_TYPED — boolesche Werte, Ganzzahlen und null behalten ihre nativen PHP-Typen (siehe unten).

Die Funktion gibt bei Erfolg ein Array zurück oder false bei einem Fehler (z. B. wenn die Datei nicht existiert). Überprüfen Sie daher immer das Ergebnis, bevor Sie es verwenden.

Verwendung der parse_ini_file()-Funktion

Beginnen Sie mit einer Konfigurationsdatei im INI-Format. Kommentare beginnen mit einem Semikolon (;):

config.ini

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

Dann parsen Sie die Datei und lesen die Werte per Schlüssel aus:

Eine flache INI-Datei einlesen

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

Die Prüfung auf === false ist wichtig: parse_ini_file() gibt bei einem Fehler false zurück (fehlende Datei, nicht lesbarer Pfad), und das Behandeln dieses Werts als Array würde Warnungen auslösen.

Einstellungen mit Abschnitten gruppieren

Echte Konfigurationsdateien sind in der Regel in [sections] unterteilt. Übergeben Sie true als zweites Argument, um diese Struktur als verschachteltes Array beizubehalten:

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

Wenn $process_sections auf true gesetzt ist, wird jeder Abschnitt zu einem Unter-Array. Dadurch wird verhindert, dass Schlüssel mit demselben Namen (z. B. ein gemeinsamer host in zwei Abschnitten) sich gegenseitig überschreiben.

Typisierung von Werten (Scanner-Modi)

Standardmäßig wird jeder Wert als String zurückgegeben — boolesche Werte werden in "1" oder einen leeren String "" umgewandelt, und Zahlen bleiben textuell:

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

Wenn Sie native PHP-Typen benötigen, verwenden Sie 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)

Dies ist der sicherste Modus, wenn Ihr Code auf echte boolesche Werte angewiesen ist (if ($c['enabled'])), anstatt auf wahrheitsgemäße Strings — beachten Sie, dass der String "0" und der leere String beide als falsy ausgewertet werden, aber "false" im NORMAL-Modus als truthy ausgewertet würde, was eine häufige Fehlerquelle ist.

Reservierte Wörter und Fallstricke

Einige Zeichen und Wörter haben in INI-Dateien eine besondere Bedeutung und können zu Überraschungen führen:

• Reservierte Werte: null, yes, no, true, false, on, off, none werden interpretiert. Um sie wörtlich zu behalten, setzen Sie den Wert in Anführungszeichen: mode = "off".
• Reservierte Zeichen: ?{}|&~!()^" dürfen nicht in einem nicht in Anführungszeichen gesetzten Wert verwendet werden.
• Schlüssel namens null, yes, no, true, false, on, off, none sind als Schlüssel nicht erlaubt.
• Das ; beginnt einen Kommentar, daher muss ein Wert, der ein Semikolon enthält, in Anführungszeichen gesetzt werden.

Bei nicht vertrauenswürdigen oder vom Benutzer hochgeladenen Dateien empfiehlt sich die sicherere Variante parse_ini_string() nach dem Einlesen der Datei mit file_get_contents(), oder validieren Sie den Pfad zuerst — parsen Sie niemals beliebige, vom Benutzer angegebene Pfade.

Wann sollte parse_ini_file() verwendet werden?

parse_ini_file() eignet sich gut, wenn Sie eine menschlich editierbare Konfigurationsdatei wünschen, die auch Nicht-Entwickler anpassen können, und wenn die Daten flache Key/Value-Einstellungen sind. Für tief verschachtelte oder array-lastige Daten sind JSON (json_decode()) oder PHP-Arrays, die aus einer per require eingebundenen Datei zurückgegeben werden, in der Regel die bessere Wahl. Siehe PHP File Handling für den vollständigen Satz von Datei-Funktionen und PHP Constants, da INI-Werte im INI_SCANNER_NORMAL-Modus auf definierte Konstanten verweisen können.

Fazit

Die parse_ini_file()-Funktion wandelt eine INI-Konfigurationsdatei in einem einzigen Aufruf in ein PHP-Array um. Denken Sie an die drei häufigsten Stolperfallen: Prüfen Sie auf einen false-Rückgabewert, übergeben Sie true für $process_sections, wenn Ihre Datei [sections] verwendet, und verwenden Sie INI_SCANNER_TYPED, wenn Sie echte boolesche Werte und Ganzzahlen anstelle von Strings benötigen.

Übung