xmlwriter_write_dtd_entity — Funktion · PHP-Referenz

Signatur

xmlwriter_write_dtd_entity(XMLWriter $writer, string $name, string $content, bool $isParam = false, string $publicId = "", string $systemId = "", string $notationData = ""): bool

Beschreibung

xmlwriter_write_dtd_entity() erzeugt eine vollständige DTD-Entitätsdeklaration (<!ENTITY …>) und gibt sie direkt in den internen Puffer des XMLWriter-Objekts aus. Die Funktion kombiniert die Schritte des prozeduralen Äquivalents von xmlwriter_start_dtd_entity() und xmlwriter_end_dtd_entity() in einem einzigen Aufruf.

Entitäten in DTDs erlauben es, häufig verwendete Texte oder externe Ressourcen unter einem Namen zusammenzufassen, der im Dokument dann per &name; referenziert werden kann. Parameterentitäten (mit $isParam = true) werden dagegen innerhalb der DTD selbst mit %name; referenziert.

Sollen externe Entitäten deklariert werden, können $publicId, $systemId und optionale Notationsdaten ($notationData) übergeben werden. Für einfache interne Entitäten genügen $name und $content.

Die Funktion muss innerhalb eines geöffneten DTD-Blocks aufgerufen werden, also nachdem xmlwriter_start_dtd() (oder xmlwriter_write_dtd()) aufgerufen wurde.

Parameter

Name	Typ	Default	Beschreibung
$writer Pflicht	XMLWriter		Die `XMLWriter`-Instanz, in die geschrieben wird.
$name Pflicht	string		Der Name der Entität, über den sie im Dokument referenziert wird.
$content Pflicht	string		Der Inhalt der internen Entität. Bei externen Entitäten kann dieser Wert leer sein.
$isParam	bool	false	Gibt an, ob es sich um eine Parameterentität (`%name;`) handelt. Bei `false` handelt es sich um eine allgemeine Entität (`&name;`).
$publicId	string	""	Die öffentliche Kennung (Public Identifier) für externe Entitäten, z. B. `-//W3C//DTD XHTML 1.0//EN`. Leer lassen, wenn nicht benötigt.
$systemId	string	""	Die System-URI für externe Entitäten, z. B. eine URL oder Dateipfad. Leer lassen, wenn nicht benötigt.
$notationData	string	""	Optionaler Name einer Notation für nicht-geparste externe Entitäten (NDATA-Deklaration). Wird selten benötigt.

Rückgabewert

Typ

bool

Beschreibung

Gibt true bei Erfolg zurück, false bei einem Fehler (z. B. wenn kein DTD-Block geöffnet ist).

Beispiele

Einfache interne Entität in einer DTD schreiben

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

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

// Interne Entität schreiben
xmlwriter_write_dtd_entity($writer, 'copyright', '© 2024 Mein Unternehmen');

$writer->endDtd();
$writer->startElement('katalog');
$writer->writeRaw('&copyright;');
$writer->endElement();
$writer->endDocument();

echo $writer->outputMemory();

Parameterentität und externe Entität mit SYSTEM-ID

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

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

// Parameterentität (wird in der DTD selbst verwendet)
xmlwriter_write_dtd_entity($writer, 'gemeinsam', 'id CDATA #REQUIRED', true);

// Externe Entität mit System-ID
xmlwriter_write_dtd_entity($writer, 'logo', '', false, '', 'images/logo.png', 'GIF');

$writer->endDtd();
$writer->startElement('buch');
$writer->endElement();
$writer->endDocument();

echo $writer->outputMemory();

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE buch [ <!ENTITY % gemeinsam "id CDATA #REQUIRED"> <!ENTITY logo SYSTEM "images/logo.png" NDATA GIF> ]> <buch/>

// Wichtig · Fallstricke

Sicherheitshinweis: DTD-Entitäten können bei der Verarbeitung von XML-Eingaben zu sogenannten XXE-Angriffen (XML External Entity Injection) führen. Wenn extern gelieferte Inhalte in DTD-Entitäten einfließen, immer sorgfältig validieren und sanitisieren. Nutze LIBXML_NOENT in der XML-Verarbeitung nur wenn absolut notwendig.

Die Funktion muss zwischen xmlwriter_start_dtd() und xmlwriter_end_dtd() aufgerufen werden, da DTD-Entitäten nur innerhalb eines DTD-Blocks gültig sind. Außerhalb dieses Blocks schlägt der Aufruf fehl und gibt false zurück.

Ab PHP 8.0 wird die objektorientierte Methode XMLWriter::writeDtdEntity() bevorzugt; die prozedurale Form bleibt aber weiterhin verfügbar.

Siehe auch

xmlwriter_start_dtd_entity xmlwriter_end_dtd_entity xmlwriter_write_dtd xmlwriter_start_dtd xmlwriter_end_dtd xmlwriter_write_dtd_element xmlwriter_write_dtd_attlist