Signatur
Beschreibung
Dom\Entity ist Teil der modernen, namespaced DOM-API (eingeführt in PHP 8.4) und repräsentiert eine Entitätsdeklaration aus der Document Type Definition (DTD) eines XML-Dokuments. Entitäten können entweder intern (mit einem direkten Ersetzungstext) oder extern (mit einem Verweis auf eine externe Ressource via System- oder Public-Identifier) sein.
Objekte dieses Typs befinden sich im Dom\DocumentType::$entities-NamedNodeMap und können über diese Sammlung abgerufen werden. Eine direkte Instanziierung ist nicht vorgesehen; Instanzen entstehen ausschließlich beim Parsen eines XML-Dokuments mit einer DTD, die Entitätsdeklarationen enthält.
Die Klasse stellt schreibgeschützte Eigenschaften bereit, mit denen man auf die Bestandteile der Entitätsdeklaration zugreifen kann: publicId, systemId, notationName (für nicht geparste Entitäten) sowie den internen Ersetzungstext. Im Gegensatz zur älteren DOMEntity-Klasse (aus der DOM-Erweiterung) verwendet diese Klasse den strengen PHP-8-Typansatz mit korrekten Nullability-Angaben.
Diese Klasse ist besonders relevant, wenn XML-Dokumente mit komplexen DTDs verarbeitet werden und man Metadaten über deklarierte Entitäten (z. B. für Validierung oder Dokumentinspektion) benötigt.
Beispiele
Entitätsdeklarationen aus einer DTD auslesen
<?php
$xml = <<<XML
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE root [
<!ENTITY greet "Hallo Welt">
<!ENTITY ext SYSTEM "http://example.com/extern.xml">
]>
<root>&greet;</root>
XML;
$dom = Dom\XMLDocument::createFromString($xml);
$doctype = $dom->doctype;
if ($doctype !== null) {
$entities = $doctype->entities;
foreach ($entities as $name => $entity) {
/** @var Dom\Entity $entity */
echo "Name: " . $entity->nodeName . "\n";
echo "SystemId: " . ($entity->systemId ?? '(keine)') . "\n";
echo "PublicId: " . ($entity->publicId ?? '(keine)') . "\n";
echo "NotationName: " . ($entity->notationName ?? '(keine)') . "\n";
echo "---\n";
}
}Prüfen ob eine bestimmte Entität in der DTD existiert
<?php
$xml = <<<XML
<?xml version="1.0"?>
<!DOCTYPE doc [
<!ENTITY copy "©">
<!ENTITY img SYSTEM "bild.gif" NDATA gif>
]>
<doc>©</doc>
XML;
$dom = Dom\XMLDocument::createFromString($xml);
$entities = $dom->doctype?->entities;
if ($entities !== null && $entities->getNamedItem('img') instanceof Dom\Entity) {
$entity = $entities->getNamedItem('img');
echo "Nicht geparste Entität gefunden.\n";
echo "Notation: " . $entity->notationName . "\n";
echo "System-ID: " . $entity->systemId . "\n";
}// Wichtig · Fallstricke
Schreibschutz: Alle Eigenschaften von Dom\Entity sind read-only. Versuche, sie zu schreiben, führen zu einem Fehler. Entitätsdeklarationen können nur durch Manipulation der DTD selbst geändert werden, was die PHP-DOM-API nicht direkt unterstützt.
Sicherheitshinweis: Beim Verarbeiten von XML aus nicht vertrauenswürdigen Quellen sollte man auf XML External Entity (XXE)-Angriffe achten. Externe Entitäten (mit systemId) können dazu missbraucht werden, lokale Dateien auszulesen. Dom\XMLDocument::createFromString() deaktiviert in PHP 8.4 standardmäßig das Laden externer Entitäten.
Kompatibilität: Dom\Entity ist nicht identisch mit DOMEntity aus der älteren ext/dom-Erweiterung. Beide existieren parallel; Dom\Entity gehört zur neuen, spec-konformen DOM-Implementierung.