yaml_emit_file — Funktion · PHP-Referenz

Signatur

yaml_emit_file(string $filename, mixed $data, int $encoding = YAML_ANY_ENCODING, int $linebreak = YAML_ANY_BREAK, array $callbacks = []): bool

Beschreibung

yaml_emit_file() serialisiert einen PHP-Wert als YAML und schreibt das Ergebnis in die angegebene Datei. Die Funktion ist das dateibasierte Pendant zu yaml_emit(), das die YAML-Darstellung als Zeichenkette zurückgibt.

Die Funktion eignet sich überall dort, wo Konfigurationsdaten, strukturierte Informationen oder Exportdaten persistent als YAML-Datei gespeichert werden sollen – zum Beispiel beim Speichern von Anwendungseinstellungen, beim Export von Datensätzen oder beim Erzeugen von Fixtures für Tests.

Über den optionalen Parameter $callbacks lässt sich das Serialisierungsverhalten für bestimmte Datentypen individuell anpassen. Jeder Eintrag im Array ordnet einem YAML-Tag eine PHP-Callback-Funktion zu, die den Wert vor der Ausgabe transformiert.

Voraussetzung ist, dass die PECL-Erweiterung yaml installiert und aktiviert ist, da yaml_emit_file() nicht zum PHP-Kern gehört.

Parameter

Name	Typ	Default	Beschreibung
$filename Pflicht	string		Pfad zur Zieldatei, in die der YAML-Inhalt geschrieben wird. Wenn die Datei noch nicht existiert, wird sie angelegt; eine vorhandene Datei wird überschrieben.
$data Pflicht	mixed		Der PHP-Wert (Array, Objekt, Skalar usw.), der in YAML serialisiert werden soll.
$encoding	int	YAML_ANY_ENCODING	Zeichenkodierung der YAML-Ausgabe. Mögliche Werte: `YAML_ANY_ENCODING`, `YAML_UTF8_ENCODING`, `YAML_UTF16LE_ENCODING`, `YAML_UTF16BE_ENCODING`.
$linebreak	int	YAML_ANY_BREAK	Zeilenumbruchstil der Ausgabe. Mögliche Werte: `YAML_ANY_BREAK`, `YAML_CR_BREAK`, `YAML_LN_BREAK`, `YAML_CRLN_BREAK`.
$callbacks	array	[]	Assoziatives Array von YAML-Tag zu PHP-Callable, das die Serialisierung bestimmter Datentypen anpassen kann. Beispiel: `['!mytype' => 'myCallbackFn']`.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn die Datei erfolgreich geschrieben wurde, andernfalls false.

Beispiele

Konfiguration als YAML-Datei speichern

<?php
$config = [
    'database' => [
        'host'     => 'localhost',
        'port'     => 3306,
        'name'     => 'myapp',
        'user'     => 'root',
        'password' => 'secret',
    ],
    'cache' => [
        'driver'  => 'redis',
        'ttl'     => 3600,
    ],
    'debug' => false,
];

$result = yaml_emit_file('/var/www/config/app.yaml', $config, YAML_UTF8_ENCODING, YAML_LN_BREAK);

if ($result) {
    echo "Konfigurationsdatei erfolgreich gespeichert.";
} else {
    echo "Fehler beim Schreiben der Datei.";
}

Konfigurationsdatei erfolgreich gespeichert.

Datensatz mit benutzerdefiniertem Callback exportieren

<?php
// Callback, der DateTime-Objekte als ISO-8601-Zeichenkette serialisiert
function dateTimeEmitter(DateTime $value): string {
    return $value->format(DateTime::ATOM);
}

$data = [
    'title'   => 'Besprechungsprotokoll',
    'created' => new DateTime('2024-06-01 10:00:00'),
    'items'   => ['Tagesordnung', 'Budget', 'AOB'],
];

// Hinweis: Der Callback-Schlüssel muss dem YAML-Tag entsprechen,
// das für das Objekt verwendet werden soll.
$success = yaml_emit_file(
    '/tmp/protokoll.yaml',
    $data,
    YAML_UTF8_ENCODING,
    YAML_LN_BREAK,
    ['tag:yaml.org,2002:timestamp' => 'dateTimeEmitter']
);

var_dump($success);

bool(true)

// Wichtig · Fallstricke

Dateisystemberechtigungen: Der PHP-Prozess benötigt Schreibrechte auf das Zielverzeichnis. Existiert die Zieldatei bereits, wird sie ohne Rückfrage überschrieben – prüfen Sie daher ggf. mit file_exists(), ob eine Sicherung nötig ist.

Erweiterung erforderlich: yaml_emit_file() ist Teil der PECL-Erweiterung yaml (basiert auf libyaml) und steht nicht in Standard-PHP-Installationen zur Verfügung. Prüfen Sie mit extension_loaded('yaml'), ob die Erweiterung geladen ist.

Sicherheit: Schreiben Sie YAML-Dateien niemals in öffentlich erreichbare Verzeichnisse des Webservers, wenn diese sensible Daten (Passwörter, API-Schlüssel) enthalten. Validieren Sie den $filename-Parameter, wenn er aus Benutzereingaben stammt, um Path-Traversal-Angriffe zu verhindern.

Siehe auch

yaml_emit yaml_parse_file yaml_parse