xml_set_unparsed_entity_decl_handler()

La funzione xml_set_unparsed_entity_decl_handler() imposta un callback definito dall'utente come gestore per le dichiarazioni di entità non analizzate in un parser XML. Appartiene all'estensione XML Parser (SAX) di PHP e fa parte della stessa famiglia di xml_set_element_handler() e xml_set_character_data_handler() — non si applica a SimpleXML o DOM.

Un'entità non analizzata è un'entità il cui contenuto il processore XML non deve analizzare come XML — tipicamente un riferimento a dati binari esterni come un'immagine, un PDF o un file audio. Viene dichiarata con la parola chiave NDATA seguita da un nome di notazione, ad esempio:

<!ENTITY logo SYSTEM "logo.png" NDATA png>

Quando il parser incontra tale dichiarazione nel DTD del documento, invoca il tuo gestore in modo che tu possa registrare dove si trova la risorsa invece di provare a caricarla come markup.

Sintassi

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

Valore restituito: restituisce sempre true.

Nota PHP 8: a partire da PHP 8.0 il parser è un oggetto XMLParser anziché una resource, ma il codice che scrivi è identico — continua a trattare il valore restituito da xml_parser_create() come un handle opaco.

La firma del callback

Il tuo gestore viene chiamato con sei argomenti, in questo ordine:

handler(
    XMLParser $parser,
    string $entityName,    // e.g. "logo"
    string $base,          // base URI used to resolve the system id (often empty)
    string $systemId,      // e.g. "logo.png"
    string $publicId,      // public id, if any
    string $notationName   // e.g. "png" — declared with xml_set_notation_decl_handler()
): void

Esempio: acquisire le dichiarazioni di entità non analizzate

Crea un parser SAX con xml_parser_create(), registra il gestore, poi fornisci l'XML a xml_parse():

<?php
function handleUnparsedEntity($parser, $name, $base, $systemId, $publicId, $notationName) {
    echo "Unparsed entity '$name' -> $systemId (notation: $notationName)\n";
}

$xmlParser = xml_parser_create();
xml_set_unparsed_entity_decl_handler($xmlParser, "handleUnparsedEntity");

$xml = '<?xml version="1.0"?>
<!DOCTYPE catalog [
  <!NOTATION png SYSTEM "image/png">
  <!ENTITY logo SYSTEM "logo.png" NDATA png>
  <!ENTITY manual SYSTEM "manual.pdf" NDATA pdf>
]>
<catalog/>';

xml_parse($xmlParser, $xml, true);
xml_parser_free($xmlParser);

Output atteso:

Unparsed entity 'logo' -> logo.png (notation: png)
Unparsed entity 'manual' -> manual.pdf (notation: pdf)

Il gestore si attiva una volta per ogni entità NDATA nel DTD, fornendoti il percorso del file ($systemId) e la notazione. Un'applicazione reale memorizzerebbe questi riferimenti — ad esempio per scaricare le risorse in seguito — invece di stamparli.

Errori comuni

• Il DTD deve contenere dichiarazioni NDATA. Un'entità interna normale (<!ENTITY name "value">) è testo analizzato, quindi questo gestore non la vedrà mai. Solo le entità contrassegnate con NDATA notation sono "non analizzate".
• Registra i gestori prima di chiamare xml_parse(). Come ogni funzione xml_set_*_handler(), questa non ha effetto una volta avviato il parsing.
• Libera il parser con xml_parser_free() quando hai finito, per rilasciare le risorse.
• Non disponibile in SimpleXML. Se stai leggendo XML ben formato e non hai bisogno di reagire alle dichiarazioni di entità del DTD, il più semplice parser SimpleXML è solitamente la scelta migliore.

Funzioni correlate

• xml_parser_create() — crea il parser SAX a cui questo gestore si collega.
• xml_set_notation_decl_handler() — gestisce le dichiarazioni <!NOTATION ...> referenziate dalle entità non analizzate.
• xml_set_external_entity_ref_handler() — gestisce i riferimenti a entità esterne analizzate.
• xml_set_element_handler() — gestisce gli eventi di inizio/fine elemento.

Conclusione

xml_set_unparsed_entity_decl_handler() consente a un parser SAX di notificarti le entità NDATA — riferimenti a dati binari esterni — in modo che tu possa acquisire i loro percorsi e notazioni senza tentare di analizzarle come XML. Registra il gestore prima di xml_parse(), aspettati il callback a sei argomenti e ricorda che la funzione si applica solo all'estensione XML Parser procedurale, non a SimpleXML o DOM.

Esercizio