Signatur
Beschreibung
xmlwriter_start_document() eröffnet ein neues XML-Dokument und erzeugt den XML-Prolog, also die Verarbeitungsanweisung <?xml version="1.0" encoding="UTF-8" ?>. Sie muss in der Regel als erster Schreibaufruf erfolgen, bevor Elemente, Attribute oder andere Knoten hinzugefügt werden.
Die Funktion arbeitet im prozeduralen Stil mit einem XMLWriter-Objekt, das zuvor mit xmlwriter_open_memory() oder xmlwriter_open_uri() erstellt wurde. In der objektorientierten Variante existiert die entsprechende Methode XMLWriter::startDocument().
Mit den optionalen Parametern lassen sich die XML-Version, die Zeichenkodierung sowie die Standalone-Deklaration festlegen. Diese Angaben landen direkt im Prolog und haben Einfluss darauf, wie Parser und Browser das Dokument interpretieren.
Nach dem Erzeugen des Dokument-Starts sollten alle geöffneten Elemente und am Ende das Dokument selbst mit xmlwriter_end_document() geschlossen werden, um wohlgeformtes XML zu erhalten.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $writer Pflicht | XMLWriter | Die XMLWriter-Instanz, in die geschrieben wird. Wird mit xmlwriter_open_memory() oder xmlwriter_open_uri() erstellt. |
|
| $version | ?string | 1.0 | Die XML-Version, die im Prolog angegeben wird. In der Praxis wird fast immer '1.0' verwendet. null lässt die Angabe weg. |
| $encoding | ?string | Die Zeichenkodierung des Dokuments, z. B. 'UTF-8' oder 'ISO-8859-1'. Wird null übergeben, erscheint kein encoding-Attribut im Prolog. |
|
| $standalone | ?string | Gibt an, ob das Dokument standalone ist. Gültige Werte sind 'yes' oder 'no'. Bei null wird die Standalone-Deklaration weggelassen. |
Rückgabewert
true zurück, wenn der XML-Prolog erfolgreich geschrieben wurde, andernfalls false.Beispiele
Einfaches XML-Dokument mit Prolog erstellen
<?php
$writer = xmlwriter_open_memory();
xmlwriter_set_indent($writer, true);
xmlwriter_set_indent_string($writer, ' ');
// Dokument-Prolog mit Version und Kodierung
xmlwriter_start_document($writer, '1.0', 'UTF-8');
xmlwriter_start_element($writer, 'root');
xmlwriter_write_element($writer, 'message', 'Hallo Welt');
xmlwriter_end_element($writer);
xmlwriter_end_document($writer);
echo xmlwriter_output_memory($writer);XML-Dokument mit Standalone-Deklaration in Datei schreiben
<?php
$writer = xmlwriter_open_uri('/tmp/ausgabe.xml');
xmlwriter_set_indent($writer, true);
// Prolog mit Version, Kodierung und standalone="yes"
xmlwriter_start_document($writer, '1.0', 'UTF-8', 'yes');
xmlwriter_start_element($writer, 'katalog');
xmlwriter_start_element($writer, 'produkt');
xmlwriter_write_attribute($writer, 'id', '42');
xmlwriter_write_element($writer, 'name', 'PHP-Buch');
xmlwriter_end_element($writer);
xmlwriter_end_element($writer);
xmlwriter_end_document($writer);
echo 'XML-Datei erfolgreich geschrieben.';// Wichtig · Fallstricke
Reihenfolge beachten: xmlwriter_start_document() muss vor allen anderen Schreiboperationen aufgerufen werden. Ein nachträglicher Aufruf führt zu einem ungültigen XML-Dokument.
Kodierung und tatsächliche Daten: Die Angabe von encoding im Prolog deklariert lediglich, welche Kodierung verwendet wird – PHP stellt nicht sicher, dass die tatsächlich geschriebenen Daten dieser Kodierung entsprechen. Es liegt in der Verantwortung des Entwicklers, dass alle Zeichenketten korrekt kodiert sind, z. B. durch mb_convert_encoding().
OOP-Äquivalent: Im objektorientierten Stil lautet die entsprechende Methode XMLWriter::startDocument() mit identischen Parametern.