yaml_parse_url — Funktion · PHP-Referenz

Signatur

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

Beschreibung

yaml_parse_url() lädt den Inhalt einer URL über PHP-Streamwrapper und interpretiert ihn als YAML-Dokument oder -Stream. Das Ergebnis wird als entsprechender PHP-Typ zurückgegeben (z. B. array, string, int usw.), je nachdem, was das YAML-Dokument beschreibt.

Der Parameter $pos bestimmt, welches Dokument aus einem Multi-Dokument-Stream (durch --- getrennte Dokumente) zurückgegeben werden soll. Mit dem Wert -1 werden alle Dokumente als Array zurückgegeben. Der optionale Referenzparameter $ndocs wird nach dem Parsen mit der Gesamtanzahl der gefundenen Dokumente im Stream befüllt.

Über $callbacks können benutzerdefinierte YAML-Tags auf PHP-Callbacks gemappt werden, um beim Parsen spezifische Typen oder Objekte zu erzeugen. Dies ist nützlich, wenn eigene YAML-Tags wie !php/object oder domänenspezifische Tags verarbeitet werden müssen.

Die Funktion unterstützt alle von PHP registrierten Streamwrapper, daher funktioniert sie nicht nur mit http://- oder ftp://-URLs, sondern auch mit file://- oder anderen Protokollen. Sie erfordert die PECL-Erweiterung yaml (basierend auf libyaml).

Parameter

Name	Typ	Default	Beschreibung
$url Pflicht	string		Die URL, von der der YAML-Inhalt geladen werden soll. Unterstützt alle von PHP registrierten Streamwrapper, z. B. `http://`, `ftp://`, `file://`.
$pos	int	0	Index des zu parsenden Dokuments im Stream (0-basiert). `-1` gibt alle Dokumente als Array zurück.
$ndocs	int		Wird als Referenz übergeben und nach dem Parsen mit der Anzahl der im Stream gefundenen Dokumente befüllt.
$callbacks	array	[]	Assoziatives Array, das YAML-Tag-Namen auf PHP-Callbacks mappt. Die Callbacks werden aufgerufen, wenn der entsprechende Tag beim Parsen gefunden wird. Beispiel: `['!mytype' => 'mytype_callback']`.

Rückgabewert

Typ

mixed

Beschreibung

Gibt den geparsten PHP-Wert zurück (z. B. array, string, int, bool). Bei $pos = -1 wird immer ein array aller Dokumente zurückgegeben. Im Fehlerfall (z. B. URL nicht erreichbar oder ungültiges YAML) wird false zurückgegeben.

Beispiele

YAML-Konfiguration von einer lokalen Datei-URL laden

<?php
// config.yaml enthält:
// database:
//   host: localhost
//   port: 3306
//   name: mydb

$data = yaml_parse_url('file:///var/www/config.yaml');

if ($data === false) {
    echo 'Fehler beim Laden oder Parsen der YAML-Datei.';
} else {
    echo 'DB-Host: ' . $data['database']['host'] . PHP_EOL;
    echo 'DB-Port: ' . $data['database']['port'] . PHP_EOL;
}

DB-Host: localhost DB-Port: 3306

Multi-Dokument-Stream parsen und Dokumentanzahl ermitteln

<?php
// multi.yaml enthält:
// ---
// name: Alice
// ---
// name: Bob
// ---
// name: Charlie

$ndocs = 0;
$allDocs = yaml_parse_url('file:///var/www/multi.yaml', -1, $ndocs);

echo 'Anzahl Dokumente: ' . $ndocs . PHP_EOL;
foreach ($allDocs as $index => $doc) {
    echo "Dokument $index: " . $doc['name'] . PHP_EOL;
}

Anzahl Dokumente: 3 Dokument 0: Alice Dokument 1: Bob Dokument 2: Charlie

YAML mit benutzerdefiniertem Tag und Callback laden

<?php
function point_callback(array $value): object {
    $pt = new stdClass();
    $pt->x = $value['x'];
    $pt->y = $value['y'];
    return $pt;
}

// point.yaml enthält:
// location: !point
//   x: 10
//   y: 25

$data = yaml_parse_url(
    'file:///var/www/point.yaml',
    0,
    $ndocs,
    ['!point' => 'point_callback']
);

echo 'X: ' . $data['location']->x . PHP_EOL;
echo 'Y: ' . $data['location']->y . PHP_EOL;

X: 10 Y: 25

// Wichtig · Fallstricke

Sicherheitshinweis: Beim Laden von YAML-Dateien über externe URLs (z. B. http://) besteht das Risiko, nicht vertrauenswürdigen Inhalt zu verarbeiten. YAML-Callbacks können dazu missbraucht werden, beliebigen PHP-Code auszuführen – verwende daher niemals ungeprüfte externe Quellen in Verbindung mit mächtigen Callbacks wie unserialize oder ähnlichen Funktionen.

Damit externe URLs über http:// geladen werden können, muss die PHP-INI-Einstellung allow_url_fopen aktiviert sein. In restriktiven Produktionsumgebungen ist diese Option häufig deaktiviert.

Die Funktion setzt die PECL-Erweiterung yaml voraus, die auf libyaml aufbaut und nicht standardmäßig in PHP enthalten ist. Prüfe die Verfügbarkeit mit extension_loaded('yaml').

Bei ungültigem YAML-Inhalt oder nicht erreichbarer URL wird false zurückgegeben und eine E_WARNING-Meldung ausgegeben.

Siehe auch

yaml_parse yaml_parse_file yaml_emit yaml_emit_file