xml_set_processing_instruction_handler()

La fonction xml_set_processing_instruction_handler() définit une fonction utilisateur comme gestionnaire pour les instructions de traitement dans un parseur XML. Elle appartient à l'extension héritée xml (Expat / SAX) et est utilisée pour l'analyse événementielle, et non avec la bibliothèque SimpleXML. Chaque fois que le parseur rencontre une instruction de traitement dans le document, il appelle votre gestionnaire afin que vous puissiez y réagir — par exemple, pour extraire des directives incorporées ou déclencher une action en cours d'analyse.

Cette page explique ce que sont les instructions de traitement, la syntaxe et les paramètres de la fonction, un exemple complet exécutable, la signature du gestionnaire, les pièges courants et les alternatives modernes à privilégier aujourd'hui.

⚠️ Avis de dépréciation : L'extension xml a été dépréciée dans PHP 8.0 et complètement supprimée dans PHP 8.2. Cette fonction n'est disponible que dans PHP 7.4 et versions antérieures. Pour les projets modernes, utilisez XMLReader ou DOMDocument à la place.

Qu'est-ce qu'une instruction de traitement ?

Une instruction de traitement (PI) est un nœud XML spécial qui transmet des instructions spécifiques à l'application au logiciel qui lit le document. Il ne s'agit pas d'un contenu d'élément — elle se situe entre le balisage. Une PI comporte deux parties : une cible (le nom juste après <?) et des données (tout ce qui précède le ?> de fermeture) :

<?target data ?>

Par exemple, <?php-cache ttl="60" ?> a pour cible php-cache et pour données ttl="60". La déclaration XML <?xml version="1.0"?> ressemble à une PI mais est traitée de manière spéciale et ne déclenche pas ce gestionnaire.

Syntaxe

La syntaxe de la fonction xml_set_processing_instruction_handler() est la suivante :

xml_set_processing_instruction_handler($parser, $handler)

Où $parser est la ressource de parseur XML retournée par xml_parser_create(), et $handler est un callable ou une chaîne contenant le nom de la fonction utilisateur qui traitera les instructions de traitement. Passez une chaîne vide ("") pour supprimer un gestionnaire précédemment enregistré.

Paramètres

Valeur de retour

Retourne true en cas de succès, ou false si $parser n'est pas un parseur XML valide.

La signature du gestionnaire

Votre gestionnaire est appelé avec exactement trois arguments :

function handler($parser, string $target, string $data): void

• $parser — le parseur qui a déclenché le callback.
• $target — la cible de la PI (le nom immédiatement après <?).
• $data — le reste de la PI, sous forme de chaîne brute. Vous êtes responsable de son analyse ; le parseur XML ne la décompose pas en attributs.

Exemples d'utilisation

Examinons un exemple pratique d'utilisation de xml_set_processing_instruction_handler() en PHP.

Exemple : Définir une fonction de gestionnaire d'instructions de traitement

Supposons que vous disposez d'une chaîne XML contenant des instructions de traitement. Vous pouvez utiliser la fonction xml_parser_create() pour créer un nouveau parseur XML, puis définir une fonction de gestionnaire d'instructions de traitement avec xml_set_processing_instruction_handler(), comme ceci :

function handle_processing_instruction($parser, $target, $data) {
    echo "Processing instruction found: $target - $data\n";
}

$xml_parser = xml_parser_create();
xml_set_processing_instruction_handler($xml_parser, "handle_processing_instruction");

$xml_data = '<?xml version="1.0"?><root><?PI target data?></root>';
if (!xml_parse($xml_parser, $xml_data)) {
    echo "XML parse error: " . xml_error_string(xml_get_error_code($xml_parser));
}

xml_parser_free($xml_parser);

Ce code crée un nouveau parseur avec xml_parser_create(). Il définit ensuite une fonction personnalisée pour gérer les instructions de traitement. La fonction xml_parse() traite la chaîne XML et déclenche le gestionnaire lorsqu'elle rencontre une instruction de traitement. La valeur de retour est vérifiée afin que xml_error_string() puisse signaler les erreurs d'analyse. Enfin, xml_parser_free() libère la ressource du parseur après utilisation.

Sous PHP 7.4, le programme affiche :

Processing instruction found: PI - target data

Exemple : Analyser les données PI en options

Les données PI arrivent sous forme de chaîne brute unique, donc toute structure à l'intérieur est à votre charge. Un pattern courant consiste à traiter les données comme des paires key="value" :

function pi_handler($parser, $target, $data) {
    // Pull out key="value" pairs from the PI data
    preg_match_all('/(\w+)="([^"]*)"/', $data, $pairs, PREG_SET_ORDER);
    $options = [];
    foreach ($pairs as $pair) {
        $options[$pair[1]] = $pair[2];
    }
    echo "Target: $target\n";
    print_r($options);
}

$parser = xml_parser_create();
xml_set_processing_instruction_handler($parser, "pi_handler");
xml_parse($parser, '<root><?cache ttl="60" scope="page"?></root>');
xml_parser_free($parser);

Sous PHP 7.4, cela affiche :

Target: cache
Array
(
    [ttl] => 60
    [scope] => page
)

Gestionnaires associés

xml_set_processing_instruction_handler() fait partie d'une famille de configurateurs de gestionnaires SAX. Vous en enregistrez généralement plusieurs ensemble sur le même parseur :

• xml_set_element_handler() — balises d'ouverture et de fermeture.
• xml_set_character_data_handler() — texte entre les balises.
• xml_set_default_handler() — tout ce qu'aucun autre gestionnaire ne capture.
• xml_set_object() — achemine les gestionnaires vers des méthodes d'objet plutôt que des fonctions simples.

Pièges courants

• La déclaration XML n'est pas une PI ici. <?xml ... ?> est consommée par le parseur et n'atteint jamais votre gestionnaire.
• Les données ne sont pas analysées. $data est une chaîne unique. Le parseur ne décompose pas le contenu key="value" en attributs — analysez-le vous-même.
• Le gestionnaire doit être défini avant l'analyse. Enregistrez le gestionnaire avant d'appeler xml_parse(), sinon les premières instructions sont manquées.
• PHP 8.2+ n'a plus l'extension xml. Toutes les fonctions xml_* ont disparu ; les exemples de cette page ne s'exécutent que sous PHP 7.4 ou antérieur.

Conclusion

Dans cet article, nous avons abordé la fonction PHP xml_set_processing_instruction_handler() et la manière dont elle peut être utilisée pour définir un gestionnaire d'instructions de traitement pour un parseur XML dans l'extension héritée xml. Nous en avons expliqué la syntaxe et fourni un exemple pratique. Notez que, l'extension xml ayant été supprimée dans PHP 8.2, les applications modernes devraient préférer XMLReader ou DOMDocument pour le traitement XML. Pour les bases de code héritées fonctionnant sous PHP 7.4 ou antérieur, cette fonction reste un moyen fiable de gérer les instructions de traitement lors de l'analyse SAX.

Pratique