xml_set_notation_decl_handler — Funktion · PHP-Referenz

Signatur

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

Beschreibung

xml_set_notation_decl_handler setzt einen Handler, der immer dann aufgerufen wird, wenn der XML-Parser eine Notation-Deklaration im Document Type Definition (DTD) des XML-Dokuments verarbeitet. Notationen sind benannte Verweise auf externe Nicht-XML-Daten oder externe Binärdaten (z. B. Bildformate, Anwendungen) innerhalb eines DTD-Blocks.

Eine Notation-Deklaration hat die Form <!NOTATION name SYSTEM 'uri'> oder <!NOTATION name PUBLIC 'public_id' 'uri'>. Trifft der Parser auf eine solche Deklaration, wird die registrierte Callback-Funktion mit den entsprechenden Informationen aufgerufen.

Der Handler-Callback muss die folgende Signatur besitzen: handler(XMLParser $parser, string $notation_name, string $base, string $system_id, string $public_id): void. Dabei ist notation_name der Name der Notation, base die Basis-URI (in der Regel leer), system_id die System-Kennung und public_id die öffentliche Kennung der Notation.

Diese Funktion ist vor allem in Szenarien relevant, in denen XML-Dokumente mit DTDs verarbeitet werden, die externe Nicht-XML-Entitäten oder Medientypen über Notationen referenzieren – etwa in bestimmten Publishing- oder Dokumentenmanagement-Systemen.

Parameter

Name	Typ	Default	Beschreibung
$parser Pflicht	XMLParser		Eine gültige XML-Parser-Ressource, die mit `xml_parser_create()` oder `xml_parser_create_ns()` erzeugt wurde.
$handler Pflicht	callable		Der Callback, der bei einer Notation-Deklaration aufgerufen wird. Die Signatur lautet: `handler(XMLParser $parser, string $notation_name, string $base, string $system_id, string $public_id): void`. Es kann auch ein leerer String `''` übergeben werden, um einen zuvor gesetzten Handler zu deaktivieren.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn der Handler erfolgreich gesetzt wurde, andernfalls false (z. B. wenn $parser kein gültiger XML-Parser ist).

Beispiele

Notation-Deklarationen aus einem XML-Dokument mit DTD auslesen

<?php
$xml = <<<'XML'
<?xml version="1.0"?>
<!DOCTYPE root [
  <!NOTATION png SYSTEM "image/png">
  <!NOTATION jpeg PUBLIC "-//JPEG//Format//EN" "image/jpeg">
]>
<root></root>
XML;

$parser = xml_parser_create();

function notationHandler(
    XMLParser $parser,
    string $notationName,
    string $base,
    string $systemId,
    string $publicId
): void {
    echo "Notation gefunden: {$notationName}\n";
    echo "  System-ID: {$systemId}\n";
    echo "  Public-ID: {$publicId}\n";
    echo "  Basis:     {$base}\n";
    echo "---\n";
}

xml_set_notation_decl_handler($parser, 'notationHandler');

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

xml_parser_free($parser);

Notation gefunden: png System-ID: image/png Public-ID: Basis: --- Notation gefunden: jpeg System-ID: image/jpeg Public-ID: -//JPEG//Format//EN Basis: ---

Handler mit einer Objekt-Methode registrieren

<?php
class NotationCollector {
    public array $notations = [];

    public function handle(
        XMLParser $parser,
        string $notationName,
        string $base,
        string $systemId,
        string $publicId
    ): void {
        $this->notations[$notationName] = [
            'system_id' => $systemId,
            'public_id' => $publicId,
        ];
    }
}

$xml = <<<'XML'
<?xml version="1.0"?>
<!DOCTYPE root [
  <!NOTATION gif SYSTEM "image/gif">
]>
<root/>
XML;

$collector = new NotationCollector();
$parser = xml_parser_create();

xml_set_notation_decl_handler($parser, [$collector, 'handle']);
xml_parse($parser, $xml, true);
xml_parser_free($parser);

print_r($collector->notations);

Array ( [gif] => Array ( [system_id] => image/gif [public_id] => ) )

// Wichtig · Fallstricke

Hinweis zur DTD-Verarbeitung: PHP's eingebauter XML-Parser (Expat) validiert die DTD nicht vollständig. Notation-Handler werden nur für inline-deklarierte DTD-Blöcke aufgerufen; externe DTD-Referenzen werden nicht aufgelöst.

Deprecation: Ab PHP 8.0 ist der Ressourcentyp für XML-Parser durch die Klasse XMLParser ersetzt worden. Älterer Code, der eine Ressource erwartet, sollte entsprechend angepasst werden.

Leerer Handler: Übergibt man als $handler einen leeren String, wird ein zuvor registrierter Handler deaktiviert, ohne den Parser-Zustand anderweitig zu beeinflussen.

Siehe auch

xml_parser_create xml_set_unparsed_entity_decl_handler xml_set_element_handler xml_parse xml_parser_free