xmlwriter_flush — Funktion · PHP-Referenz

Signatur

xmlwriter_flush(XMLWriter $writer, bool $empty = true): string|int

Beschreibung

xmlwriter_flush() leert den internen Puffer des angegebenen XMLWriter-Objekts. Wurde der Writer im Speicher-Modus erstellt (via xmlwriter_open_memory()), gibt die Funktion den gepufferten XML-Inhalt als string zurück. Wurde der Writer hingegen im Datei-Modus erstellt (via xmlwriter_open_uri()), werden die gepufferten Daten in die Datei geschrieben und die Anzahl der ausgegebenen Bytes als int zurückgegeben.

Der optionale Parameter $empty steuert, ob der Puffer nach dem Auslesen geleert werden soll. Standardmäßig ist er true, sodass nach dem Aufruf der Puffer wieder leer ist. Setzt man ihn auf false, bleibt der bisherige Inhalt erhalten — was jedoch selten nützlich ist.

Diese Funktion ist besonders hilfreich, wenn ein großes XML-Dokument Stück für Stück aufgebaut und zwischendurch an den Client gesendet oder in eine Datei geschrieben werden soll, ohne das gesamte Dokument im Speicher halten zu müssen. Sie kann mehrfach während der Konstruktion eines Dokuments aufgerufen werden.

Seit PHP 8.0 wird die objektorientierte Variante $writer->flush() bevorzugt, während der prozedurale Aufruf mit XMLWriter-Ressourcen als erstem Parameter weiterhin unterstützt wird.

Parameter

Name	Typ	Default	Beschreibung
$writer Pflicht	XMLWriter		Das `XMLWriter`-Objekt (prozedurale API: die XMLWriter-Ressource), dessen Puffer ausgegeben werden soll.
$empty	bool	true	Gibt an, ob der Puffer nach dem Auslesen geleert werden soll. Bei `true` (Standard) wird der Puffer zurückgesetzt; bei `false` bleibt der bisherige Inhalt erhalten.

Rückgabewert

Typ

string|int

Beschreibung

Wurde der Writer im Speicher-Modus (xmlwriter_open_memory()) erstellt, wird der gepufferte XML-Inhalt als string zurückgegeben. Im Datei-Modus (xmlwriter_open_uri()) wird die Anzahl der in die Datei geschriebenen Bytes als int zurückgegeben.

Beispiele

XML im Speicher aufbauen und mit flush() ausgeben

<?php
$writer = new XMLWriter();
$writer->openMemory();
$writer->startDocument('1.0', 'UTF-8');
$writer->startElement('root');
$writer->writeElement('item', 'Erster Eintrag');
$writer->writeElement('item', 'Zweiter Eintrag');
$writer->endElement();
$writer->endDocument();

// Puffer auslesen und leeren
$xml = $writer->flush();
echo $xml;

<?xml version="1.0" encoding="UTF-8"?> <root><item>Erster Eintrag</item><item>Zweiter Eintrag</item></root>

Schrittweises Senden großer XML-Dokumente per flush()

<?php
$writer = new XMLWriter();
$writer->openMemory();
$writer->startDocument('1.0', 'UTF-8');
$writer->startElement('produkte');

// Simuliert eine große Datenmenge
$produkte = [
    ['id' => 1, 'name' => 'Apfel'],
    ['id' => 2, 'name' => 'Banane'],
    ['id' => 3, 'name' => 'Kirsche'],
];

foreach ($produkte as $produkt) {
    $writer->startElement('produkt');
    $writer->writeAttribute('id', $produkt['id']);
    $writer->writeElement('name', $produkt['name']);
    $writer->endElement();

    // Puffer zwischendurch leeren und ausgeben
    echo $writer->flush();
}

$writer->endElement();
$writer->endDocument();
echo $writer->flush();

<produkt id="1"><name>Apfel</name></produkt><produkt id="2"><name>Banane</name></produkt><produkt id="3"><name>Kirsche</name></produkt></produkte>

XML in eine Datei schreiben und Bytes zählen

<?php
$writer = new XMLWriter();
$writer->openUri('/tmp/ausgabe.xml');
$writer->startDocument('1.0', 'UTF-8');
$writer->startElement('daten');
$writer->writeElement('wert', 'Hallo Welt');
$writer->endElement();
$writer->endDocument();

$bytes = $writer->flush();
echo "Geschriebene Bytes: " . $bytes;

Geschriebene Bytes: 78

// Wichtig · Fallstricke

Puffer-Verhalten: Nach einem Aufruf von flush(true) (Standard) ist der interne Puffer leer. Nachfolgende Aufrufe ohne weitere Schreiboperationen liefern einen leeren String zurück.

Reihenfolge beachten: flush() sollte erst nach abgeschlossenen XML-Strukturen aufgerufen werden, da sonst unvollständige Tags im Puffer landen können, die zwar gültig ausgegeben, aber im Kontext fehlerhaft sein können. Idealerweise wird endDocument() vor dem letzten flush()-Aufruf aufgerufen.

Prozedurale vs. OOP-API: Ab PHP 8.0 akzeptiert die prozedurale Variante ein XMLWriter-Objekt statt einer Ressource. Die OOP-Variante $writer->flush() ist empfohlen und in neuem Code zu bevorzugen.

Siehe auch

xmlwriter_open_memory xmlwriter_open_uri xmlwriter_output_memory xmlwriter_end_document xmlwriter_start_document