xml_set_notation_decl_handler()

Die Funktion xml_set_notation_decl_handler() registriert einen benutzerdefinierten Callback, den der SAX-Parser (Expat) aufruft, sobald er eine Notation-Deklaration in der DTD des Dokuments findet. Sie gehört zur PHP-Erweiterung xml und funktioniert ausschließlich mit einem Parser, der durch xml_parser_create() erstellt wurde — bei SimpleXML oder DOM hat sie keine Wirkung.

Eine Notation-Deklaration sieht innerhalb eines <!DOCTYPE ...> folgendermaßen aus:

<!NOTATION png SYSTEM "image/png">

Notationen benennen ein externes Datenformat (einen Bildtyp, ein Hilfsprogramm usw.), damit das Format später von einer nicht geparsten Entität referenziert werden kann. In modernem XML sind sie selten, doch wenn eine DTD solche Deklarationen enthält, ermöglicht dieser Handler, sie während des Parsens abzufangen, zu protokollieren oder zu validieren, anstatt sie stillschweigend zu verwerfen.

Hinweis: Die Erweiterung xml (Expat) muss in Ihrer PHP-Installation aktiviert sein. Notation-Deklarationen kommen nur innerhalb einer internen oder externen DTD vor, sodass ein Dokument ohne <!DOCTYPE> diesen Handler niemals auslöst.

Syntax

xml_set_notation_decl_handler(
    XMLParser $parser,
    callable|false $handler
): bool

• $parser — die Parser-Ressource, die von xml_parser_create() (oder xml_parser_create_ns()) zurückgegeben wurde.
• $handler — der Callback, der für jede Notation-Deklaration aufgerufen wird, oder false, um einen zuvor gesetzten Handler zu entfernen.

Die Funktion gibt true bei Erfolg zurück und false, wenn $parser kein gültiger Parser ist.

Die Callback-Signatur

Ihr Handler erhält fünf Argumente in dieser festen Reihenfolge:

function handler($parser, $notation_name, $base, $system_id, $public_id)

Eine Notation kann SYSTEM (nur System-Bezeichner) oder PUBLIC (öffentlicher Bezeichner und ein System-Bezeichner) verwenden; prüfen Sie daher, welche Felder belegt sind, bevor Sie sich auf sie verlassen.

Beispiel: Notation-Deklarationen auslesen

Der folgende Parser gibt jede gefundene Notation aus, einschließlich der Formen SYSTEM und PUBLIC:

function handle_notation_decl($parser, $notation_name, $base, $system_id, $public_id) {
    echo "Notation name: $notation_name\n";
    echo "  System ID:   " . ($system_id ?? '(none)') . "\n";
    echo "  Public ID:   " . ($public_id ?? '(none)') . "\n";
}

$xml_parser = xml_parser_create();
xml_set_notation_decl_handler($xml_parser, "handle_notation_decl");

$xml_data = <<<XML
<?xml version="1.0"?>
<!DOCTYPE root [
  <!NOTATION png SYSTEM "image/png">
  <!NOTATION gif PUBLIC "-//IETF//NOTATION GIF89a//EN" "http://www.w3.org/Graphics/GIF/spec-gif89a.txt">
]>
<root/>
XML;

if (!xml_parse($xml_parser, $xml_data, true)) {
    echo "XML error: " . xml_error_string(xml_get_error_code($xml_parser)) . "\n";
}
xml_parser_free($xml_parser);

Dies gibt aus:

Notation name: png
  System ID:   image/png
  Public ID:   (none)
Notation name: gif
  System ID:   http://www.w3.org/Graphics/GIF/spec-gif89a.txt
  Public ID:   -//IETF//NOTATION GIF89a//EN

Beachten Sie, dass bei der SYSTEM-Notation nur die System-ID gesetzt ist, während die PUBLIC-Notation beide Bezeichner befüllt. Das dritte Argument true bei xml_parse() markiert die Daten als letztes Datenstück, und xml_parser_free() gibt den Parser frei, wenn Sie fertig sind.

Häufige Fallstricke

• Keine DTD, kein Callback. Der Handler wird nur für <!NOTATION>-Deklarationen ausgelöst, die innerhalb von <!DOCTYPE> stehen. Ein einfaches Dokument löst ihn niemals aus.
• Vor dem Parsen registrieren. Setzen Sie den Handler, bevor Sie xml_parse() zum ersten Mal aufrufen; Deklarationen werden gemeldet, während der Parser die DTD liest.
• Eine Methode als Callback verwenden. Übergeben Sie [$object, 'method'] (oder binden Sie es mit xml_set_object()), wenn der Handler zu einer Klasse gehört.
• Mit nicht geparsten Entitäten kombinieren. Notationen werden normalerweise von NDATA-Entitäten referenziert — behandeln Sie diese mit xml_set_unparsed_entity_decl_handler().

Verwandte Handler

xml_set_notation_decl_handler() ist einer von mehreren SAX-Callbacks, die Sie an denselben Parser anhängen können:

• xml_set_element_handler() — Start- und End-Tags.
• xml_set_character_data_handler() — Textinhalt.
• xml_set_unparsed_entity_decl_handler() — nicht geparste (NDATA) Entitäten.
• xml_set_default_handler() — alles ohne einen spezifischen Handler.

Fazit

xml_set_notation_decl_handler() ermöglicht das Abfangen von <!NOTATION>-Deklarationen während des SAX-Parsens, anstatt sie zu ignorieren. Registrieren Sie einen Callback mit fünf Argumenten vor dem Parsen, untersuchen Sie die empfangenen System- und Public-Bezeichner, und kombinieren Sie ihn mit den anderen xml_set_*-Handlern, um ein DTD-gesteuertes Dokument vollständig zu verarbeiten. Weiterführende Informationen finden Sie im Kapitel PHP XML Parser.

Übungen