Signatur
Beschreibung
xmlwriter_write_element() erzeugt ein komplettes XML-Element bestehend aus öffnendem Tag, optionalem Textinhalt und schließendem Tag. Die Funktion kombiniert also xmlwriter_start_element(), xmlwriter_text() und xmlwriter_end_element() in einem einzigen Schritt.
Der Parameter $content wird automatisch korrekt als XML-Text escaped, d. h. Sonderzeichen wie <, > und & werden in ihre entsprechenden Entities umgewandelt. Wenn $content null oder ein leerer String ist, wird ein selbstschließendes Element (<tag/>) bzw. ein leeres Element erzeugt.
Diese Funktion ist besonders nützlich beim Aufbau von XML-Dokumenten, wenn ein Element keinen weiteren Kind-Elemente enthält, sondern nur einfachen Textinhalt aufweist – etwa bei Pflichtfeldern in einer XML-Konfiguration oder bei einfachen Datenelementen in einem Exportformat.
Die prozedurale Variante xmlwriter_write_element() arbeitet mit einer XMLWriter-Instanz, die zuvor mit xmlwriter_open_memory() oder xmlwriter_open_uri() erstellt wurde. Ab PHP 8.0 wird XMLWriter als Objekt übergeben; in älteren Versionen war es eine Ressource.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $writer Pflicht | XMLWriter | Die XMLWriter-Instanz, in die das Element geschrieben wird. |
|
| $name Pflicht | string | Der lokale Name des zu schreibenden XML-Elements (ohne Namespace-Präfix). Muss ein gültiger XML-Bezeichner sein. | |
| $content | ?string | null | Der Textinhalt des Elements. Sonderzeichen werden automatisch escaped. Bei null oder leerem String wird ein leeres Element geschrieben. |
Rückgabewert
true zurück, wenn das Element erfolgreich geschrieben wurde, andernfalls false (z. B. bei einem ungültigen Element-Namen).Beispiele
Einfaches XML-Element schreiben
<?php
$writer = xmlwriter_open_memory();
xmlwriter_set_indent($writer, true);
xmlwriter_start_document($writer, '1.0', 'UTF-8');
xmlwriter_start_element($writer, 'person');
xmlwriter_write_element($writer, 'vorname', 'Max');
xmlwriter_write_element($writer, 'nachname', 'Mustermann');
xmlwriter_write_element($writer, 'alter', '30');
xmlwriter_end_element($writer);
xmlwriter_end_document($writer);
echo xmlwriter_output_memory($writer);Sonderzeichen werden automatisch escaped
<?php
$writer = xmlwriter_open_memory();
xmlwriter_start_document($writer, '1.0', 'UTF-8');
xmlwriter_start_element($writer, 'daten');
// Sonderzeichen wie <, > und & werden automatisch korrekt maskiert
xmlwriter_write_element($writer, 'beschreibung', 'Preis < 100 & Rabatt > 10%');
xmlwriter_end_element($writer);
xmlwriter_end_document($writer);
echo xmlwriter_output_memory($writer);Leeres Element ohne Inhalt
<?php
$writer = xmlwriter_open_memory();
xmlwriter_start_document($writer, '1.0', 'UTF-8');
xmlwriter_start_element($writer, 'config');
// null ergibt ein selbstschließendes Element
xmlwriter_write_element($writer, 'leer', null);
xmlwriter_end_element($writer);
xmlwriter_end_document($writer);
echo xmlwriter_output_memory($writer);// Wichtig · Fallstricke
Namespace-Unterstützung: Soll das Element einem Namespace angehören, muss stattdessen xmlwriter_write_element_ns() verwendet werden, das zusätzlich Präfix und Namespace-URI akzeptiert.
Nur für einfache Textelemente: Diese Funktion eignet sich nur für Elemente mit reinem Textinhalt. Sollen Kind-Elemente, Attribute oder gemischter Inhalt geschrieben werden, müssen xmlwriter_start_element(), die jeweiligen Schreib-Funktionen und xmlwriter_end_element() separat aufgerufen werden.
Ressource vs. Objekt: Vor PHP 8.0 war der erste Parameter eine Ressource vom Typ resource. Ab PHP 8.0 ist es eine XMLWriter-Objektinstanz. Der prozedurale Stil bleibt aber weiterhin verfügbar.