xmlwriter_start_dtd_entity — Funktion · PHP-Referenz

Signatur

xmlwriter_start_dtd_entity(XMLWriter $writer, string $name, bool $ispе): bool

Beschreibung

xmlwriter_start_dtd_entity() startet eine DTD-Entitätsdeklaration (<!ENTITY ...>) innerhalb einer Document Type Definition (DTD). Eine solche Deklaration legt eine Abkürzung für wiederverwendbare Texte oder externe Ressourcen fest, die später im Dokument referenziert werden können.

Der Parameter ispе steuert, ob es sich um eine Parameter-Entität (Präfix %, nur innerhalb der DTD verwendbar) oder um eine reguläre allgemeine Entität handelt. Allgemeine Entitäten werden im Dokumentinhalt über &name; referenziert.

Nach dem Aufruf dieser Funktion muss der Entitätswert mit xmlwriter_write_dtd_entity() oder einzelnen Schreiboperationen gesetzt und die Deklaration mit xmlwriter_end_dtd_entity() abgeschlossen werden. Die Funktion muss innerhalb eines geöffneten DTD-Blocks aufgerufen werden (xmlwriter_start_dtd()).

Diese prozeduale Funktion ist das Äquivalent zur Methode XMLWriter::startDtdEntity() in der objektorientierten Schreibweise.

Parameter

Name	Typ	Beschreibung
$writer Pflicht	XMLWriter	Die `XMLWriter`-Instanz, auf der operiert wird. Bei prozeduraler Verwendung wird das per `xmlwriter_open_memory()` oder `xmlwriter_open_uri()` erzeugte Objekt übergeben.
$name Pflicht	string	Der Name der Entität, z. B. `"company"`. Dieser Name wird später im Dokument als Referenz (`&company;`) verwendet.
$ispе Pflicht	bool	Gibt an, ob die Entität eine Parameter-Entität ist (`true`) oder eine allgemeine Entität (`false`). Parameter-Entitäten werden mit `%name;` innerhalb der DTD referenziert.

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

Allgemeine DTD-Entität mit prozeduraler API deklarieren

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

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

// DTD öffnen
xmlwriter_start_dtd($writer, 'root', null, null);

// Allgemeine Entität beginnen (kein Parameter-Entity)
xmlwriter_start_dtd_entity($writer, 'company', false);
xmlwriter_text($writer, 'Acme Corporation');
xmlwriter_end_dtd_entity($writer);

// DTD schließen
xmlwriter_end_dtd($writer);

// Root-Element
xmlwriter_start_element($writer, 'root');
xmlwriter_text($writer, 'Hersteller: &company;');
xmlwriter_end_element($writer);

xmlwriter_end_document($writer);

echo xmlwriter_output_memory($writer);

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE root [ <!ENTITY company "Acme Corporation"> ]> <root>Hersteller: &company;</root>

Parameter-Entität in der DTD deklarieren (OOP-Stil)

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

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

// Parameter-Entität (ispе = true)
$writer->startDtdEntity('common-attrs', true);
$writer->text('id ID #REQUIRED name CDATA #IMPLIED');
$writer->endDtdEntity();

$writer->endDtd();

$writer->startElement('catalog');
$writer->endElement();

$writer->endDocument();

echo $writer->outputMemory();

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE catalog [ <!ENTITY % common-attrs "id ID #REQUIRED name CDATA #IMPLIED"> ]> <catalog/>

// Wichtig · Fallstricke

Reihenfolge beachten: xmlwriter_start_dtd_entity() muss innerhalb eines geöffneten DTD-Blocks (zwischen xmlwriter_start_dtd() und xmlwriter_end_dtd()) aufgerufen werden. Ein Aufruf außerhalb führt zu false als Rückgabe und einem ungültigen XML-Dokument.

Abschluss nicht vergessen: Jeder Aufruf von xmlwriter_start_dtd_entity() muss mit einem entsprechenden xmlwriter_end_dtd_entity() abgeschlossen werden.

Sicherheit: DTD-Entitäten können bei der Verarbeitung durch XML-Parser zu sicherheitskritischen Problemen führen (z. B. XML External Entity Injection, XXE). Verarbeiten Sie generierte XML-Dokumente mit DTD-Entitäten nur in kontrollierten Umgebungen und deaktivieren Sie externe Entitäten im Parser, wenn fremde Eingaben verarbeitet werden.

Siehe auch

xmlwriter_end_dtd_entity xmlwriter_write_dtd_entity xmlwriter_start_dtd xmlwriter_end_dtd xmlwriter_start_dtd_element xmlwriter_start_dtd_attlist