xml_set_unparsed_entity_decl_handler()

La fonction xml_set_unparsed_entity_decl_handler() définit un callback utilisateur comme gestionnaire des déclarations d'entités non analysées dans un analyseur XML. Elle appartient à l'extension XML Parser (SAX) de PHP et fait partie de la même famille que xml_set_element_handler() et xml_set_character_data_handler() — elle ne s'applique pas à SimpleXML ni au DOM.

Une entité non analysée est une entité dont le contenu ne doit pas être analysé comme du XML par le processeur — il s'agit généralement d'une référence à des données binaires externes telles qu'une image, un PDF ou un fichier audio. Elle est déclarée avec le mot-clé NDATA suivi d'un nom de notation, par exemple :

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

Lorsque l'analyseur rencontre une telle déclaration dans la DTD du document, il invoque votre gestionnaire pour que vous puissiez enregistrer l'emplacement de la ressource au lieu d'essayer de la charger comme du balisage.

Syntaxe

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

Valeur de retour : retourne toujours true.

Note PHP 8 : depuis PHP 8.0, l'analyseur est un objet XMLParser plutôt qu'une resource, mais le code que vous écrivez est identique — continuez à traiter la valeur retournée par xml_parser_create() comme un handle opaque.

La signature du callback

Votre gestionnaire est appelé avec six arguments, dans cet ordre :

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

Exemple : capturer les déclarations d'entités non analysées

Créez un analyseur SAX avec xml_parser_create(), enregistrez le gestionnaire, puis transmettez le XML à 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);

Résultat attendu :

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

Le gestionnaire se déclenche une fois par entité NDATA dans la DTD, vous fournissant le chemin du fichier ($systemId) et la notation. Une application réelle stockerait ces références — par exemple pour télécharger les ressources ultérieurement — plutôt que de les afficher.

Erreurs courantes

• La DTD doit contenir des déclarations NDATA. Une entité interne normale (<!ENTITY name "value">) est du texte analysé, donc ce gestionnaire ne la verra jamais. Seules les entités marquées NDATA notation sont « non analysées ».
• Enregistrez les gestionnaires avant d'appeler xml_parse(). Comme toutes les fonctions xml_set_*_handler(), celle-ci n'a aucun effet une fois l'analyse commencée.
• Libérez l'analyseur avec xml_parser_free() lorsque vous avez terminé afin de libérer les ressources.
• Pas dans SimpleXML. Si vous lisez du XML bien formé et n'avez pas besoin de réagir aux déclarations d'entités DTD, l'analyseur SimpleXML est généralement le meilleur choix.

Fonctions associées

• xml_parser_create() — créer l'analyseur SAX auquel ce gestionnaire est rattaché.
• xml_set_notation_decl_handler() — gérer les déclarations <!NOTATION ...> référencées par les entités non analysées.
• xml_set_external_entity_ref_handler() — gérer les références d'entités externes analysées.
• xml_set_element_handler() — gérer les événements de début/fin d'élément.

Conclusion

xml_set_unparsed_entity_decl_handler() permet à un analyseur SAX de vous notifier des entités NDATA — références à des données binaires externes — afin que vous puissiez capturer leurs chemins et notations sans essayer de les analyser comme du XML. Enregistrez le gestionnaire avant xml_parse(), attendez-vous à un callback à six arguments, et rappelez-vous que la fonction s'applique uniquement à l'extension XML Parser procédurale, pas à SimpleXML ni au DOM.

Pratique