yaml_emit — Funktion · PHP-Referenz

Signatur

yaml_emit(mixed $data, int $encoding = YAML_ANY_ENCODING, int $linebreak = YAML_ANY_BREAK, array $callbacks = []): string|false

Beschreibung

yaml_emit() konvertiert einen beliebigen PHP-Wert – Skalare, Arrays, Objekte oder verschachtelte Strukturen – in eine valide YAML-Darstellung als String. Die Funktion ist das Gegenstück zu yaml_parse() und wird typischerweise zum Serialisieren von Konfigurationsdaten, zum Exportieren von Datenstrukturen oder zum Erzeugen von YAML-Ausgaben für APIs und Dateisysteme eingesetzt.

Der Parameter encoding legt die Zeichenkodierung des erzeugten YAML-Dokuments fest. Mögliche Werte sind YAML_ANY_ENCODING (Standard, UTF-8), YAML_UTF8_ENCODING, YAML_UTF16LE_ENCODING und YAML_UTF16BE_ENCODING. Ebenso kann der Zeilenumbruch-Typ über den Parameter linebreak gesteuert werden (z. B. YAML_LN_BREAK für Unix-Zeilenumbrüche).

Mit dem optionalen callbacks-Array lassen sich benutzerdefinierte Tag-Handler registrieren, die das Serialisierungsverhalten für bestimmte PHP-Typen oder YAML-Tags überschreiben. Jeder Schlüssel im Array entspricht einem YAML-Tag, der Wert ist ein aufrufbares PHP-Callback. Dies ermöglicht etwa die spezielle Ausgabe von Datumsobjekten oder eigenen Datentypen.

Die Funktion setzt die PECL-Erweiterung yaml voraus, die auf der libYAML-Bibliothek basiert. Sie ist nicht Teil der PHP-Standardinstallation und muss separat installiert werden (pecl install yaml).

Parameter

Name	Typ	Default	Beschreibung
$data Pflicht	mixed		Der zu serialisierende PHP-Wert. Kann ein Skalar, ein Array, ein Objekt oder `null` sein.
$encoding	int	YAML_ANY_ENCODING	Zeichenkodierung des YAML-Outputs. Gültige Werte: `YAML_ANY_ENCODING`, `YAML_UTF8_ENCODING`, `YAML_UTF16LE_ENCODING`, `YAML_UTF16BE_ENCODING`.
$linebreak	int	YAML_ANY_BREAK	Art des Zeilenumbruchs im Output. Mögliche Werte: `YAML_ANY_BREAK`, `YAML_CR_BREAK`, `YAML_LN_BREAK`, `YAML_CRLN_BREAK`.
$callbacks	array	[]	Assoziatives Array mit benutzerdefinierten YAML-Tag-Handlern. Schlüssel = YAML-Tag (String), Wert = aufrufbares Callback (`callable`), das den PHP-Wert in eine YAML-kompatible Darstellung umwandelt.

Rückgabewert

Typ

string|false

Beschreibung

Gibt den serialisierten YAML-String zurück. Im Fehlerfall (z. B. bei nicht serialisierbaren Werten) wird false zurückgegeben.

Beispiele

Einfaches Array als YAML ausgeben

<?php
$daten = [
    'name'    => 'Max Mustermann',
    'alter'   => 30,
    'aktiv'   => true,
    'tags'    => ['php', 'yaml', 'entwickler'],
];

$yaml = yaml_emit($daten);
echo $yaml;

--- name: 'Max Mustermann' alter: 30 aktiv: true tags: - php - yaml - entwickler ...

YAML mit benutzerdefiniertem Callback für DateTime-Objekte

<?php
$daten = [
    'event'   => 'PHP-Konferenz',
    'datum'   => new DateTime('2024-06-15'),
];

$callbacks = [
    '!php/object' => function ($wert) {
        if ($wert instanceof DateTime) {
            return $wert->format('Y-m-d');
        }
        return (string) $wert;
    },
];

// Ohne Callback: Objekte werden standardmäßig serialisiert
$yaml = yaml_emit($daten);
echo $yaml;

// Mit explizitem DateTime-Handling über Tag-Callback
$konfig = [
    'event' => 'PHP-Konferenz',
    'datum' => '2024-06-15',
];
echo yaml_emit($konfig, YAML_UTF8_ENCODING, YAML_LN_BREAK);

--- event: 'PHP-Konferenz' datum: '2024-06-15' ...

Konfigurationsdatei erzeugen und speichern

<?php
$config = [
    'datenbank' => [
        'host'     => 'localhost',
        'port'     => 3306,
        'name'     => 'meine_db',
        'charset'  => 'utf8mb4',
    ],
    'cache' => [
        'aktiviert' => true,
        'ttl'       => 3600,
    ],
];

$yaml = yaml_emit($config, YAML_UTF8_ENCODING, YAML_LN_BREAK);

if ($yaml === false) {
    throw new RuntimeException('YAML-Serialisierung fehlgeschlagen.');
}

file_put_contents('/etc/myapp/config.yaml', $yaml);
echo "Konfiguration gespeichert.\n";

Konfiguration gespeichert.

// Wichtig · Fallstricke

Erweiterung erforderlich: yaml_emit() ist Teil der PECL-Erweiterung yaml und nicht im PHP-Kern enthalten. Die Verfügbarkeit kann mit extension_loaded('yaml') geprüft werden.

Objekte: PHP-Objekte werden standardmäßig mit dem YAML-Tag !php/object und Base64-kodierter serialize()-Ausgabe gespeichert. Das Einlesen solcher Daten mit yaml_parse() ohne entsprechenden Callback kann zu Sicherheitsproblemen führen, da dabei unserialize() verwendet wird – niemals nicht vertrauenswürdige YAML-Daten mit PHP-Objekt-Tags deserialisieren.

Ressourcen können nicht serialisiert werden und führen zu einem Fehler. Floats werden entsprechend der YAML-Spezifikation als Dezimalzahlen ausgegeben; sehr kleine oder sehr große Werte können in wissenschaftlicher Notation erscheinen.

Siehe auch

yaml_parse yaml_emit_file yaml_parse_file json_encode serialize