Dom\EntityReference — Klasse · PHP-Referenz

Signatur

class Dom\EntityReference extends Dom\Node

Beschreibung

Dom\EntityReference ist Teil der modernen, namespaced DOM-API, die mit PHP 8.4 eingeführt wurde. Sie entspricht dem EntityReference-Knoten-Typ aus der W3C-DOM-Spezifikation (Knotentyp 5) und repräsentiert einen Verweis auf eine in der DTD (Document Type Definition) deklarierte Entität, zum Beispiel & oder benutzerdefinierte Entitäten wie &myEntity;.

In einer gut geformten XML-Datei erscheinen Entitätsverweise, wenn ein Dokument geparst wird und nicht-eingebettete Entitäten referenziert werden. Dom\EntityReference-Knoten werden vom Parser automatisch erzeugt; sie werden selten programmatisch von Hand erstellt. Ihr Inhalt (die expandierte Darstellung) ist über Kindknoten zugänglich.

Die Klasse erbt alle Eigenschaften und Methoden von Dom\Node, wie z. B. nodeName (enthält den Entitätsnamen ohne & und ;) und nodeType (gibt XML_ENTITY_REF_NODE zurück). Sie besitzt keine eigenen zusätzlichen Methoden oder Eigenschaften.

Hinweis: In der Praxis expandieren moderne Browser und viele XML-Parser Entitätsverweise automatisch. Die Klasse ist vor allem bei der Verarbeitung von XML-Dokumenten mit DTD-Entitäten relevant, wenn die Struktur des DOM-Baums vollständig erhalten bleiben soll.

Beispiele

Entitätsverweis-Knoten im DOM-Baum erkennen

<?php
// XML-Dokument mit DTD und Entitätsverweis
$xmlString = <<<'XML'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE root [
  <!ENTITY greet "Hallo Welt">
]>
<root>&greet;</root>
XML;

$dom = Dom\XMLDocument::createFromString($xmlString);

// Alle Kindknoten des Root-Elements durchlaufen
$root = $dom->documentElement;
foreach ($root->childNodes as $node) {
    echo 'Knotentyp: ' . $node->nodeType . PHP_EOL;
    echo 'Knotenname: ' . $node->nodeName . PHP_EOL;
    if ($node instanceof Dom\EntityReference) {
        echo 'EntityReference gefunden: &' . $node->nodeName . ';' . PHP_EOL;
    }
}

Knotentyp: 5 Knotenname: greet EntityReference gefunden: &greet;

Entitätsverweis programmatisch erstellen und einfügen

<?php
$xmlString = <<<'XML'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE root [
  <!ENTITY company "Programmierung.net">
]>
<root></root>
XML;

$dom = Dom\XMLDocument::createFromString($xmlString);

// Neuen EntityReference-Knoten erstellen
$entityRef = $dom->createEntityReference('company');

// Zum Root-Element hinzufügen
$dom->documentElement->appendChild($entityRef);

// Ausgabe des serialisierten XML
echo $dom->saveXML($dom->documentElement);

<root>&company;</root>

// Wichtig · Fallstricke

Kompatibilität: Dom\EntityReference gehört zur neuen Dom\-Namespace-API (PHP 8.4+). Die ältere DOMEntityReference-Klasse aus der ext/dom-Erweiterung ist das Äquivalent für PHP < 8.4 und verhält sich weitgehend gleich.

Parser-Verhalten: Viele XML-Parser lösen Entitätsverweise direkt auf, sodass im DOM statt eines EntityReference-Knotens ein einfacher Text-Knoten mit dem expandierten Inhalt erscheint. Ob Entitätsverweise als eigene Knoten erhalten bleiben, hängt von den Parser-Optionen ab.

DTD erforderlich: Um Entitätsverweise korrekt zu verwenden, muss die Entität in der DTD des Dokuments deklariert sein. Andernfalls ist das XML nicht wohlgeformt und der Parser wirft einen Fehler.

Siehe auch

DOMEntityReference Dom\Node Dom\Entity Dom\Document::createEntityReference Dom\XMLDocument