xml_set_unparsed_entity_decl_handler — Funktion · PHP-Referenz

Signatur

xml_set_unparsed_entity_decl_handler(XMLParser $parser, callable $handler): bool

Beschreibung

Diese Funktion setzt den Callback-Handler für sogenannte unparsed entities (nicht geparste Entitäten) im XML-Dokument. Eine unparsed entity ist eine Entität, die im DTD-Abschnitt mit einem NDATA-Attribut deklariert wird, z. B. <!ENTITY bild SYSTEM "bild.gif" NDATA gif>. Da solche Entitäten Binärdaten oder externe Ressourcen referenzieren können, die der XML-Parser nicht selbst verarbeitet, wird stattdessen dieser Handler aufgerufen.

Der registrierte Handler wird aufgerufen, sobald der Parser eine entsprechende Entity-Deklaration im Dokumenttyp erkennt. Dabei werden der Entity-Name, die Basis-URI, die System-ID, die Public-ID sowie der Notation-Name als Parameter übergeben. Dies ist nützlich, wenn man externe Ressourcen (z. B. Bilder oder andere Binärdaten) in einem XML-Dokument verwalten möchte.

Die Funktion gehört zur älteren xml_*-API (Expat-basiert) und arbeitet mit einem per xml_parser_create() erzeugten Parser. Ab PHP 8.0 ist der erste Parameter ein XMLParser-Objekt statt einer Ressource.

Es ist zu beachten, dass dieser Handler in der Praxis selten benötigt wird, da echte unparsed-Entity-Deklarationen in modernen XML-Dokumenten kaum vorkommen. Er ist jedoch wichtig für vollständige DTD-Verarbeitung und Validierungs-Szenarien.

Parameter

Name	Typ	Default	Beschreibung
$parser Pflicht	XMLParser		Der XML-Parser, der durch `xml_parser_create()` oder `xml_parser_create_ns()` erzeugt wurde.
$handler Pflicht	callable		Der Callback-Handler, der aufgerufen wird, wenn eine unparsed entity deklariert wird. Die Funktion muss folgende Signatur haben: `handler(XMLParser $parser, string $entity_name, string $base, string $system_id, string $public_id, string $notation_name): void`. parser: Der aufrufende XML-Parser. entity_name: Name der deklarierten Entität. base: Basis-URI (meist leer). system_id: System-Identifier der Entität. public_id: Public-Identifier der Entität. notation_name: Name der zugehörigen Notation.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn der Handler erfolgreich gesetzt wurde, andernfalls false.

Beispiele

Handler für NDATA-Entity-Deklarationen registrieren

<?php
$xml = <<<XML
<?xml version="1.0"?>
<!DOCTYPE root [
  <!NOTATION gif SYSTEM "image/gif">
  <!ENTITY logo SYSTEM "logo.gif" NDATA gif>
]>
<root>&logo;</root>
XML;

$parser = xml_parser_create();

function unparsedEntityHandler(
    XMLParser $parser,
    string $entity_name,
    string $base,
    string $system_id,
    string $public_id,
    string $notation_name
): void {
    echo "Entity-Name: $entity_name\n";
    echo "System-ID: $system_id\n";
    echo "Notation: $notation_name\n";
}

xml_set_unparsed_entity_decl_handler($parser, 'unparsedEntityHandler');

if (!xml_parse($parser, $xml, true)) {
    echo 'Parse-Fehler: ' . xml_error_string(xml_get_error_code($parser));
}

xml_parser_free($parser);

Entity-Name: logo System-ID: logo.gif Notation: gif

Handler als Closure registrieren

<?php
$parser = xml_parser_create();

$entities = [];

xml_set_unparsed_entity_decl_handler(
    $parser,
    function (
        XMLParser $parser,
        string $entity_name,
        string $base,
        string $system_id,
        string $public_id,
        string $notation_name
    ) use (&$entities): void {
        $entities[$entity_name] = [
            'system_id'     => $system_id,
            'public_id'     => $public_id,
            'notation_name' => $notation_name,
        ];
    }
);

$xmlData = '<?xml version="1.0"?>'
    . '<!DOCTYPE doc ['
    . '<!NOTATION png SYSTEM "image/png">'
    . '<!ENTITY banner SYSTEM "banner.png" NDATA png>'
    . ']><doc></doc>';

xml_parse($parser, $xmlData, true);
xml_parser_free($parser);

print_r($entities);

Array ( [banner] => Array ( [system_id] => banner.png [public_id] => [notation_name] => png ) )

// Wichtig · Fallstricke

Hinweis zur Verfügbarkeit: Dieser Handler wird nur aufgerufen, wenn der XML-Parser die DTD-Deklarationen tatsächlich verarbeitet. In der Praxis unterstützen viele XML-Dokumente keine NDATA-Entitäten, weshalb dieser Handler häufig nicht ausgelöst wird.

PHP 8.0: Ab PHP 8.0 wurde der Ressource-Typ für Parser durch das XMLParser-Objekt ersetzt. Bestehender Code, der eine Ressource erwartet, muss ggf. angepasst werden.

Alternative: Für modernere XML-Verarbeitung empfiehlt sich die Verwendung von SimpleXML oder DOMDocument, die eine objektorientierte API bieten und einfacher zu handhaben sind.

Siehe auch

xml_parser_create xml_set_notation_decl_handler xml_set_element_handler xml_parse xml_parser_free xml_set_external_entity_ref_handler