xml_set_notation_decl_handler()

La funzione xml_set_notation_decl_handler() registra un callback definito dall'utente che il parser SAX (Expat) richiama ogni volta che incontra una dichiarazione di notazione nel DTD del documento. Appartiene all'estensione xml di PHP e funziona solo con un parser creato da xml_parser_create() — non ha effetto su SimpleXML o DOM.

Una dichiarazione di notazione ha questo aspetto all'interno di un <!DOCTYPE ...>:

<!NOTATION png SYSTEM "image/png">

Le notazioni assegnano un nome a un formato di dati esterno (un tipo di immagine, un programma ausiliario, ecc.) affinché il formato possa essere successivamente referenziato da un'entità non analizzata. Sono rare nell'XML moderno, ma quando un DTD le contiene, questo handler permette di intercettare, registrare o validare ciascuna di esse durante il parsing invece di ignorarla silenziosamente.

Nota: L'estensione xml (Expat) deve essere abilitata nella build di PHP. Le dichiarazioni di notazione compaiono solo all'interno di un DTD interno o esterno, quindi un documento senza <!DOCTYPE> non attiva mai questo handler.

Sintassi

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

• $parser — la risorsa parser restituita da xml_parser_create() (o xml_parser_create_ns()).
• $handler — il callback da eseguire per ogni dichiarazione di notazione, oppure false per rimuovere un handler precedentemente impostato.

Restituisce true in caso di successo e false se $parser non è un parser valido.

La firma del callback

Il tuo handler riceve cinque argomenti in questo ordine fisso:

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

Una notazione può usare SYSTEM (solo identificatore di sistema) o PUBLIC (identificatore pubblico e identificatore di sistema), quindi verifica quali campi sono popolati prima di utilizzarli.

Esempio: lettura delle dichiarazioni di notazione

Il seguente parser stampa ogni notazione trovata, incluse le forme SYSTEM e 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);

Questo stampa:

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

Si noti che per la notazione SYSTEM è impostato solo il system ID, mentre la notazione PUBLIC popola entrambi gli identificatori. Il terzo argomento true passato a xml_parse() contrassegna i dati come chunk finale, e xml_parser_free() rilascia il parser al termine.

Errori comuni

• Nessun DTD, nessun callback. L'handler si attiva solo per le dichiarazioni <!NOTATION>, che si trovano all'interno di <!DOCTYPE>. Un documento semplice non lo attiva mai.
• Registrare prima del parsing. Impostare l'handler prima della prima chiamata a xml_parse(); le dichiarazioni vengono riportate man mano che il parser legge il DTD.
• Usare un metodo come callback. Passare [$object, 'method'] (o associare con xml_set_object()) quando l'handler si trova su una classe.
• Abbinare alle entità non analizzate. Le notazioni sono normalmente referenziate da entità NDATA — gestirle con xml_set_unparsed_entity_decl_handler().

Handler correlati

xml_set_notation_decl_handler() è uno dei vari callback SAX che puoi collegare allo stesso parser:

• xml_set_element_handler() — tag di apertura e chiusura.
• xml_set_character_data_handler() — contenuto testuale.
• xml_set_unparsed_entity_decl_handler() — entità non analizzate (NDATA).
• xml_set_default_handler() — tutto ciò che non ha un handler specifico.

Conclusione

xml_set_notation_decl_handler() consente di intercettare le dichiarazioni <!NOTATION> durante il parsing SAX invece di ignorarle. Registra un callback con cinque argomenti prima del parsing, esamina gli identificatori di sistema e pubblici che riceve, e combinalo con gli altri handler xml_set_* per elaborare un documento basato su DTD dall'inizio alla fine. Per un contesto più ampio, consulta il capitolo PHP XML Parser.

Pratica