xml_set_notation_decl_handler()

La fonction xml_set_notation_decl_handler() enregistre un callback défini par l'utilisateur que le parseur SAX (Expat) invoque chaque fois qu'il rencontre une déclaration de notation dans la DTD du document. Elle appartient à l'extension xml de PHP et ne fonctionne qu'avec un parseur créé par xml_parser_create() — elle n'a aucun effet sur SimpleXML ou DOM.

Une déclaration de notation se présente ainsi dans un <!DOCTYPE ...> :

<!NOTATION png SYSTEM "image/png">

Les notations désignent un format de données externe (un type d'image, un programme auxiliaire, etc.) afin que le format puisse ensuite être référencé par une entité non analysée. Elles sont rares dans le XML moderne, mais lorsqu'une DTD en contient, ce gestionnaire vous permet de les intercepter, de les journaliser ou de les valider lors de l'analyse au lieu de les ignorer silencieusement.

Remarque : L'extension xml (Expat) doit être activée dans votre build PHP. Les déclarations de notation n'apparaissent qu'à l'intérieur d'une DTD interne ou externe, donc un document sans <!DOCTYPE> ne déclenche jamais ce gestionnaire.

Syntaxe

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

• $parser — la ressource de parseur retournée par xml_parser_create() (ou xml_parser_create_ns()).
• $handler — le callback à exécuter pour chaque déclaration de notation, ou false pour supprimer un gestionnaire précédemment défini.

La fonction retourne true en cas de succès et false si $parser n'est pas un parseur valide.

La signature du callback

Votre gestionnaire reçoit cinq arguments dans cet ordre fixe :

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

Une notation peut utiliser SYSTEM (identifiant système uniquement) ou PUBLIC (identifiant public et un identifiant système), vérifiez donc quels champs sont renseignés avant de vous y fier.

Exemple : lecture des déclarations de notation

Le parseur suivant affiche chaque notation qu'il trouve, y compris les formes SYSTEM et 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);

Cela affiche :

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

Notez que pour la notation SYSTEM, seul l'identifiant système est défini, tandis que la notation PUBLIC renseigne les deux identifiants. Le troisième argument true passé à xml_parse() marque les données comme le dernier bloc, et xml_parser_free() libère le parseur une fois que vous avez terminé.

Pièges courants

• Pas de DTD, pas de callback. Le gestionnaire se déclenche uniquement pour les déclarations <!NOTATION>, qui se trouvent dans <!DOCTYPE>. Un document ordinaire ne le déclenche jamais.
• Enregistrer avant l'analyse. Définissez le gestionnaire avant le premier appel à xml_parse() ; les déclarations sont signalées au fur et à mesure que le parseur lit la DTD.
• Utiliser une méthode comme callback. Passez [$object, 'method'] (ou liez avec xml_set_object()) lorsque le gestionnaire se trouve dans une classe.
• Associer aux entités non analysées. Les notations sont normalement référencées par des entités NDATA — gérez celles-ci avec xml_set_unparsed_entity_decl_handler().

Gestionnaires connexes

xml_set_notation_decl_handler() est l'un des nombreux callbacks SAX que vous pouvez attacher au même parseur :

• xml_set_element_handler() — balises ouvrantes et fermantes.
• xml_set_character_data_handler() — contenu textuel.
• xml_set_unparsed_entity_decl_handler() — entités non analysées (NDATA).
• xml_set_default_handler() — tout ce qui n'a pas de gestionnaire spécifique.

Conclusion

xml_set_notation_decl_handler() vous permet d'intercepter les déclarations <!NOTATION> lors de l'analyse SAX au lieu de les ignorer. Enregistrez un callback à cinq arguments avant l'analyse, inspectez les identifiants système et public qu'il reçoit, et combinez-le avec les autres gestionnaires xml_set_* pour traiter un document piloté par DTD de bout en bout. Pour un contexte plus large, consultez le chapitre PHP XML Parser.

Pratique