yaml_parse_file — Funktion · PHP-Referenz

Signatur

yaml_parse_file(string $filename, int $pos = 0, int &$ndocs = null, array $callbacks = []): mixed

Beschreibung

yaml_parse_file() öffnet die angegebene Datei, liest den YAML-Stream darin und wandelt ihn in eine entsprechende PHP-Datenstruktur um (Arrays, Skalare, null usw.). Die Funktion ist Teil der PECL-Erweiterung yaml und erfordert, dass diese installiert und aktiviert ist.

Über den Parameter $pos lässt sich bei Dateien, die mehrere YAML-Dokumente enthalten (getrennt durch ---), gezielt ein bestimmtes Dokument auswählen. Ein Wert von -1 liefert alle Dokumente als indiziertes Array zurück. Mit dem Referenz-Parameter $ndocs kann die Anzahl der enthaltenen Dokumente abgefragt werden.

Benutzerdefinierte Callbacks im Parameter $callbacks ermöglichen es, bestimmte YAML-Tags auf eigene PHP-Verarbeitungsroutinen zu mappen, etwa um spezielle Datentypen korrekt zu deserialisieren.

Die Funktion eignet sich besonders für Konfigurationsdateien im YAML-Format, da sie bequem einen direkten Dateipfad entgegennimmt, ohne dass der Inhalt vorher manuell eingelesen werden muss.

Parameter

Name	Typ	Default	Beschreibung
$filename Pflicht	string		Pfad zur YAML-Datei, die geparst werden soll. Relative Pfade werden relativ zum aktuellen Arbeitsverzeichnis aufgelöst.
$pos	int	0	Index des zu parsenden Dokuments bei Dateien mit mehreren YAML-Dokumenten. `0` = erstes Dokument, `-1` = alle Dokumente als Array.
$ndocs	int		Wird als Referenz übergeben und enthält nach dem Aufruf die Gesamtanzahl der YAML-Dokumente in der Datei.
$callbacks	array	[]	Assoziatives Array, das YAML-Tag-Namen auf PHP-Callable-Funktionen mappt. Ermöglicht benutzerdefinierte Deserialisierung bestimmter YAML-Typen.

Rückgabewert

Typ

mixed

Beschreibung

Gibt bei Erfolg die geparste PHP-Datenstruktur zurück (typischerweise ein Array oder ein Skalarwert). Bei $pos = -1 ein indiziertes Array aller Dokumente. Im Fehlerfall wird false zurückgegeben.

Beispiele

Einfache Konfigurationsdatei lesen

<?php
// config.yaml:
// database:
//   host: localhost
//   port: 3306
//   name: mydb
// debug: true

$config = yaml_parse_file('config.yaml');

if ($config === false) {
    die('Fehler beim Parsen der YAML-Datei.');
}

echo $config['database']['host']; // localhost
echo $config['database']['port']; // 3306
var_dump($config['debug']);        // bool(true)

localhost 3306 bool(true)

Datei mit mehreren YAML-Dokumenten einlesen

<?php
// multi.yaml:
// ---
// name: Alice
// age: 30
// ---
// name: Bob
// age: 25

$ndocs = 0;
$all = yaml_parse_file('multi.yaml', -1, $ndocs);

echo "Anzahl Dokumente: $ndocs\n";
foreach ($all as $doc) {
    echo $doc['name'] . ' ist ' . $doc['age'] . ' Jahre alt.' . "\n";
}

Anzahl Dokumente: 2 Alice ist 30 Jahre alt. Bob ist 25 Jahre alt.

Benutzerdefinierter Callback für eigene YAML-Tags

<?php
// data.yaml:
// ---
// created_at: !php/date '2024-01-15'

function parseDateTag(string $value, string $tag, int $flags): DateTime {
    return new DateTime($value);
}

$callbacks = ['!php/date' => 'parseDateTag'];
$data = yaml_parse_file('data.yaml', 0, $ndocs, $callbacks);

if ($data !== false) {
    echo $data['created_at']->format('d.m.Y');
}

15.01.2024

// Wichtig · Fallstricke

Sicherheitshinweis: Parsen Sie niemals YAML-Dateien aus nicht vertrauenswürdigen Quellen ohne vorherige Validierung. Insbesondere PHP-spezifische YAML-Tags (z. B. !!php/object) können bei bestimmten Erweiterungskonfigurationen zur Deserialisierung von PHP-Objekten führen und stellen ein erhebliches Sicherheitsrisiko dar. Die INI-Option yaml.decode_php sollte in Produktivumgebungen auf 0 gesetzt werden.

Die Funktion ist nicht in der PHP-Standardinstallation enthalten. Sie erfordert die PECL-Erweiterung yaml, die auf der Bibliothek libyaml basiert. Ohne installierte Erweiterung führt der Aufruf zu einem fatalen Fehler.

Für sehr große YAML-Dateien kann der Speicherverbrauch erheblich sein, da der gesamte Inhalt in eine PHP-Datenstruktur überführt wird.

Siehe auch

yaml_parse yaml_parse_url yaml_emit_file yaml_emit