yaml_parse — Funktion · PHP-Referenz

Signatur

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

Beschreibung

yaml_parse() interpretiert einen als String übergebenen YAML-Stream und wandelt die enthaltenen Strukturen in PHP-Werte um. Skalare werden zu string, int, float oder bool, Sequenzen werden zu indizierten Arrays und Mappings zu assoziativen Arrays.

Über den Parameter $pos lässt sich steuern, welches Dokument innerhalb eines Multi-Dokument-Streams (getrennt durch ---) zurückgegeben werden soll. Der Wert -1 liefert alle Dokumente als Array. Mit der Referenz-Variable $ndocs kann die Gesamtzahl der Dokumente im Stream ausgelesen werden.

Mit $callbacks können benutzerdefinierte Handler für bestimmte YAML-Tags (tags) registriert werden. So lassen sich eigene PHP-Objekte oder Typen erzeugen, wenn der Parser auf einen bestimmten YAML-Tag trifft.

Die Funktion gehört zur PECL-Erweiterung yaml (basierend auf libyaml) und steht nicht im PHP-Kern zur Verfügung. Sie muss über pecl install yaml installiert und in der php.ini aktiviert werden.

Parameter

Name	Typ	Default	Beschreibung
$input Pflicht	string		Der zu parsende YAML-String. Kann ein einzelnes oder mehrere durch `---` getrennte YAML-Dokumente enthalten.
$pos	int	0	Index (0-basiert) des Dokuments im Stream, das zurückgegeben werden soll. `-1` gibt alle Dokumente als Array zurück.
$ndocs	int		Wird als Referenz übergeben und enthält nach dem Aufruf die Anzahl der Dokumente im Stream.
$callbacks	array	[]	Assoziatives Array, das YAML-Tag-Strings auf PHP-Callable-Werte abbildet. Der Callback erhält den geparsten Wert und soll den umgewandelten PHP-Wert zurückgeben. Beispiel: `['!php/object' => 'unserialize']`.

Rückgabewert

Typ

mixed

Beschreibung

Gibt den geparsten PHP-Wert des angeforderten Dokuments zurück. Bei $pos = -1 ein Array aller Dokumente. Gibt false zurück, wenn der YAML-String nicht geparst werden konnte.

Beispiele

Einfachen YAML-String parsen

<?php
$yaml = <<<YAML
name: Max Mustermann
alter: 30
aktiv: true
hobbys:
  - Programmieren
  - Lesen
YAML;

$daten = yaml_parse($yaml);

echo $daten['name'] . PHP_EOL;      // Max Mustermann
echo $daten['alter'] . PHP_EOL;     // 30
var_dump($daten['aktiv']);           // bool(true)
print_r($daten['hobbys']);

Max Mustermann 30 bool(true) Array ( [0] => Programmieren [1] => Lesen )

Multi-Dokument-Stream parsen

<?php
$stream = <<<YAML
---
stadt: Berlin
---
stadt: München
---
stadt: Hamburg
YAML;

$alle = yaml_parse($stream, -1, $anzahl);

echo "Anzahl Dokumente: $anzahl" . PHP_EOL;
foreach ($alle as $doc) {
    echo $doc['stadt'] . PHP_EOL;
}

Anzahl Dokumente: 3 Berlin München Hamburg

Eigenen Tag-Callback verwenden

<?php
$yaml = "wert: !meintyp 42";

$callbacks = [
    '!meintyp' => function ($value) {
        return (int) $value * 100;
    },
];

$daten = yaml_parse($yaml, 0, $ndocs, $callbacks);
echo $daten['wert']; // 4200

4200

// Wichtig · Fallstricke

Sicherheitshinweis: YAML-Dateien oder -Strings aus nicht vertrauenswürdigen Quellen sollten niemals ohne Validierung geparst werden. Mit dem Callback-Mechanismus lassen sich zwar eigene Tags behandeln, jedoch kann ein präparierter YAML-String bei unbedachtem Einsatz von Callbacks wie unserialize zu Remote Code Execution (RCE) führen. Verwende niemals !!php/object-Tags mit unserialize als Callback für unbekannte Eingaben.

Die Funktion ist nicht im PHP-Kern enthalten. Sie gehört zur PECL-Erweiterung yaml. Stelle sicher, dass extension=yaml in der php.ini aktiviert ist, bevor du die Funktion verwendest.

Bei sehr großen YAML-Dokumenten oder tief verschachtelten Strukturen kann der Speicherbedarf erheblich ansteigen. Für das Parsen von YAML-Dateien steht die ergänzende Funktion yaml_parse_file() zur Verfügung.

Siehe auch

yaml_parse_file yaml_parse_url yaml_emit json_decode