xmlwriter_write_comment — Funktion · PHP-Referenz

Signatur

xmlwriter_write_comment(XMLWriter $writer, string $content): bool

Beschreibung

xmlwriter_write_comment() ist eine prozedurale Funktion der XMLWriter-Erweiterung, die einen kompletten XML-Kommentar erzeugt und ihn direkt in den internen Ausgabepuffer schreibt. Der übergebene Text wird dabei automatisch von den Kommentar-Trennzeichen  umschlossen.

Die Funktion ist eine Kurzform für die Kombination aus xmlwriter_start_comment(), xmlwriter_text() und xmlwriter_end_comment(). Sie eignet sich besonders gut, wenn ein Kommentar keine dynamisch aufgebauten Inhalte enthält und in einem einzigen Schritt geschrieben werden kann.

Typische Einsatzgebiete sind das Einbetten von Metadaten, Versionsinformationen, Lizenzhinweisen oder Debugging-Informationen direkt in eine erzeugte XML-Datei. Zu beachten ist, dass der Kommentar-Inhalt nicht die Zeichenfolge -- enthalten darf, da dies laut XML-Spezifikation ungültig ist.

Ab PHP 8.0 wird der XMLWriter-Parameter als Objekt übergeben; in älteren PHP-Versionen wurde stattdessen eine Ressource verwendet.

Parameter

Name	Typ	Default	Beschreibung
$writer Pflicht	XMLWriter		Das `XMLWriter`-Objekt (ab PHP 8.0) bzw. die XMLWriter-Ressource (PHP 5/7), in dessen Puffer der Kommentar geschrieben wird.
$content Pflicht	string		Der Textinhalt des Kommentars. Darf die Zeichenfolge `--` nicht enthalten, da dies der XML-Spezifikation widerspricht.

Rückgabewert

Typ

bool

Beschreibung

Gibt true bei Erfolg zurück, andernfalls false.

Beispiele

Einfacher XML-Kommentar mit xmlwriter_write_comment()

<?php
$writer = xmlwriter_open_memory();
xmlwriter_set_indent($writer, true);
xmlwriter_set_indent_string($writer, '  ');

xmlwriter_start_document($writer, '1.0', 'UTF-8');

// Kommentar vor dem Root-Element
xmlwriter_write_comment($writer, ' Generiert am ' . date('Y-m-d') . ' ');

xmlwriter_start_element($writer, 'root');
xmlwriter_write_element($writer, 'item', 'Wert');
xmlwriter_end_element($writer);

xmlwriter_end_document($writer);

echo xmlwriter_output_memory($writer);

<?xml version="1.0" encoding="UTF-8"?>  <root> <item>Wert</item> </root>

Kommentar als Lizenzhinweis am Dokumentanfang

<?php
$writer = new XMLWriter();
$writer->openMemory();
$writer->setIndent(true);
$writer->setIndentString('    ');

$writer->startDocument('1.0', 'UTF-8');

// Lizenzkommentar
xmlwriter_write_comment($writer, ' Dieses Dokument ist urheberrechtlich geschützt. ');

$writer->startElement('catalog');
$writer->writeElement('title', 'PHP-Handbuch');
$writer->endElement();

$writer->endDocument();

echo $writer->outputMemory();

<?xml version="1.0" encoding="UTF-8"?>  <catalog> <title>PHP-Handbuch</title> </catalog>

// Wichtig · Fallstricke

Ungültige Zeichenfolge: Der content-Parameter darf die Zeichenfolge -- (doppelter Bindestrich) nicht enthalten, da XML-Kommentare diese Sequenz laut W3C-Spezifikation nicht beinhalten dürfen. PHP prüft dies nicht automatisch; ein solcher Inhalt erzeugt möglicherweise ungültiges XML.

Objekt- vs. prozeduraler Stil: Ab PHP 8.0 ist der erste Parameter vom Typ XMLWriter (Objekt). Die objektorientierte Alternative ist $writer->writeComment($content). Beide Varianten sind funktional gleichwertig.

Keine automatische Escaping: Im Gegensatz zu Element- oder Attributinhalten wird der Kommentarinhalt nicht weiter escaped. Er sollte daher keine Sonderzeichen enthalten, die das XML-Dokument beschädigen könnten.

Siehe auch

xmlwriter_start_comment xmlwriter_end_comment xmlwriter_write_element xmlwriter_open_memory xmlwriter_output_memory