xml_get_current_column_number()

La fonction xml_get_current_column_number() est une fonction intégrée de PHP qui récupère le numéro de colonne actuel d'un parseur XML — le décalage horizontal de caractère (base 1) dans la ligne actuelle atteinte par le parseur. Elle appartient à l'extension héritée XML Parser (Expat), et non à SimpleXML ou DOM, et n'est significative que lors d'une analyse en cours.

Cette page explique ce que retourne la fonction, sa syntaxe et des exemples exécutables qui montrent le numéro de colonne rapporté depuis des gestionnaires d'événements SAX. Elle est surtout utile pour localiser précisément un élément ou une erreur dans l'entrée — par exemple, pour écrire un message de journal précis ou un diagnostic « erreur de syntaxe near colonne X ».

Comme la valeur reflète la position en direct du parseur, vous devez l'appeler depuis un gestionnaire (ou juste après l'échec de xml_parse()). Elle se combine naturellement avec xml_get_current_line_number() et xml_get_current_byte_index() pour décrire complètement une position.

Syntaxe

xml_get_current_column_number(XMLParser $parser): int|false

$parser est le parseur XML créé par xml_parser_create() (en PHP 8.0+, il s'agit d'un objet XMLParser ; dans les versions antérieures, c'était une ressource). La fonction retourne le numéro de colonne sous forme d'entier, ou false si $parser n'est pas un parseur valide.

Exemples d'utilisation

Examinons quelques exemples pratiques d'utilisation de xml_get_current_column_number() en PHP.

Exemple 1 : Récupérer le numéro de colonne actuel d'un parseur XML

Supposons que vous ayez une chaîne XML que vous souhaitez analyser avec l'extension XML Parser héritée en PHP. Vous pouvez appeler xml_get_current_column_number() dans un gestionnaire d'événements SAX — enregistré avec xml_set_element_handler() — pour récupérer la colonne où commence chaque balise :

$xml_parser = xml_parser_create();
xml_set_element_handler($xml_parser, function($parser, $name) {
    echo "Start tag: $name at column " . xml_get_current_column_number($parser) . "\n";
}, function($parser, $name) {
    echo "End tag: $name\n";
});

$xml_data = "<root>\n  <item>Test</item>\n</root>";
xml_parse($xml_parser, $xml_data);
xml_parser_free($xml_parser);

Ce code crée un parseur, enregistre des gestionnaires d'éléments de début et de fin, et exécute xml_parse() sur les données. Dans le gestionnaire de balise de début, il lit le numéro de colonne en direct et l'affiche, puis libère le parseur avec xml_parser_free(). Notez que la colonne pointe vers le caractère après l'ouvreur de la balise, donc elle avance au fur et à mesure que le parseur consomme chaque balise. La sortie est :

Start tag: ROOT at column 6
Start tag: ITEM at column 8
End tag: ITEM
End tag: ROOT

Exemple 2 : Suivre les numéros de colonne pendant l'analyse

Supposons que vous deviez suivre la position de colonne du contenu textuel lors de l'analyse d'un fichier XML. Comme xml_parse_into_struct() ne renseigne pas les numéros de colonne dans son tableau de sortie, le suivi en temps réel nécessite des gestionnaires d'événements de style SAX plutôt qu'une itération après l'analyse. Vous pouvez enregistrer un gestionnaire de données de caractères avec xml_set_character_data_handler() pour capturer les positions de colonne au fur et à mesure que le parseur rencontre du texte :

$xml_parser = xml_parser_create();
xml_set_character_data_handler($xml_parser, function($parser, $data) {
    $col = xml_get_current_column_number($parser);
    echo "Text content found at column: $col\n";
});

$xml_data = "<root>\n  <item>Sample Data</item>\n</root>";
xml_parse($xml_parser, $xml_data);
xml_parser_free($xml_parser);

Le gestionnaire de données de caractères peut se déclencher plusieurs fois par nœud de texte (par exemple, autour des espaces et des sauts de ligne), vous verrez donc généralement plusieurs colonnes rapportées. Cette approche suit les positions en temps réel, contrairement à l'itération de tableau après l'analyse, qui ne peut pas accéder à l'état dynamique du parseur. La sortie pour cette entrée est :

Text content found at column: 3
Text content found at column: 20
Text content found at column: 1

Notes et points d'attention

• Appelez-la pendant l'analyse. La valeur n'a de sens que pendant l'exécution de xml_parse() (à l'intérieur d'un gestionnaire) ou immédiatement après une erreur d'analyse. En dehors de cette fenêtre, elle n'a aucune signification utile.
• Les colonnes sont en base 1 et par ligne. Le comptage se réinitialise à chaque nouvelle ligne. Combinez-la avec xml_get_current_line_number() pour obtenir un emplacement complet ligne:colonne.
• Indice d'octet vs. colonne. Si vous avez besoin du décalage absolu depuis le début du document plutôt que la position par ligne, utilisez xml_get_current_byte_index().
• Extension héritée. Le parseur XML basé sur Expat est procédural et orienté événements. Pour la plupart des traitements de documents modernes, préférez SimpleXML ou DOM — mais pour l'analyse en flux de fichiers volumineux ou la localisation précise des erreurs, cette extension reste l'outil approprié.

Conclusion

Dans cet article, nous avons abordé la fonction PHP xml_get_current_column_number() et comment elle peut être utilisée pour récupérer le numéro de colonne actuel d'un parseur XML en PHP. Nous avons expliqué ce que fait la fonction, sa syntaxe et fourni des exemples de son utilisation dans des scénarios pratiques. En suivant ces exemples, vous pouvez facilement suivre la position actuelle d'un parseur XML pendant l'analyse et l'utiliser dans vos applications PHP pour la journalisation, le débogage ou le suivi de progression.

Pratique