xml_get_current_line_number()

La fonction xml_get_current_line_number() est une fonction intégrée PHP qui récupère le numéro de ligne actuel d'un parseur XML. Elle appartient à l'extension procédurale XML Parser (Expat) et est utilisée lors de l'analyse XML avec les fonctions SAX xml_parse*. Connaître le numéro de ligne actuel est utile pour le débogage, le rapport d'erreurs et le suivi de la progression de l'analyse.

Cette page couvre la syntaxe de la fonction, sa valeur de retour et des exemples pratiques — aussi bien avec une analyse en une seule fois qu'à l'intérieur d'un gestionnaire d'événements SAX en direct.

Quand l'utiliser

Appelez xml_get_current_line_number() chaque fois que vous avez besoin de la position du parseur dans le document source, typiquement :

• Rapport d'erreurs — lorsqu'un gestionnaire d'événements ou xml_get_error_code() signale un problème, le numéro de ligne indique à l'utilisateur où dans le fichier il s'est produit.
• Suivi de la progression — afficher quelle ligne est en cours de traitement lors de l'analyse d'un grand fichier XML.
• Diagnostics — associez-la à xml_get_current_column_number() et xml_get_current_byte_index() pour obtenir un emplacement précis ligne:colonne.

Cette fonction fait partie de l'API Expat procédurale. Si vous analysez XML avec la classe orientée objet XMLReader, utilisez plutôt sa méthode getLineNo().

Syntaxe

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

xml_get_current_line_number($parser): int|false

Paramètre

• $parser — le parseur XML créé par xml_parser_create() (ou xml_parser_create_ns()). En PHP 8+, il s'agit d'un objet XMLParser ; en PHP 7 et versions antérieures, c'est une ressource.

Valeur de retour

Retourne le numéro de ligne actuel (un int, commençant à la ligne 1) au fur et à mesure que le parseur lit le document. Elle retourne false si $parser n'est pas un parseur valide. Pendant l'analyse, la valeur reflète la ligne des données atteintes par le parseur — elle est donc plus significative lorsqu'elle est lue à l'intérieur d'un gestionnaire d'événements.

Exemples d'utilisation

Voyons quelques exemples pratiques d'utilisation de xml_get_current_line_number() en PHP.

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

Supposons que vous ayez un fichier XML data.xml que vous souhaitez analyser avec l'extension XML Parser en PHP. Vous pouvez utiliser la fonction xml_get_current_line_number() pour récupérer le numéro de ligne atteint après l'analyse, comme ceci :

$xml_parser = xml_parser_create();
xml_parser_set_option($xml_parser, XML_OPTION_CASE_FOLDING, 0);
xml_parse_into_struct($xml_parser, file_get_contents("data.xml"), $values);
$current_line_number = xml_get_current_line_number($xml_parser);
echo "Current Line Number: $current_line_number";
xml_parser_free($xml_parser);

Ce code crée un parseur XML avec xml_parser_create(), et définit une option pour désactiver le repliage de casse. Il utilise ensuite xml_parse_into_struct() pour analyser le fichier XML data.xml et stocker le résultat dans un tableau $values. Il récupère le numéro de ligne actuel avec xml_get_current_line_number(), qui retourne le numéro de ligne du dernier élément analysé, et l'affiche dans la console. Enfin, il libère la mémoire utilisée par le parseur XML avec xml_parser_free().

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

Supposons que vous souhaitiez suivre le numéro de ligne de chaque élément au fur et à mesure de son analyse via un gestionnaire d'événements SAX. Vous pouvez utiliser xml_set_element_handler() avec xml_get_current_line_number() pour surveiller la position du parseur en temps réel, comme ceci :

$xml_parser = xml_parser_create();
xml_set_element_handler($xml_parser, function($parser, $name, $attrs) {
    $line = xml_get_current_line_number($parser);
    echo "Element <$name> found at line $line\n";
}, function($parser, $name) {
    // end element handler
});
$xml_data = file_get_contents("data.xml");
xml_parse($xml_parser, $xml_data, true);
xml_parser_free($xml_parser);

Ce code crée un parseur XML avec xml_parser_create(), et enregistre un gestionnaire d'éléments avec xml_set_element_handler(). Il utilise ensuite xml_parse() pour analyser le fichier XML data.xml. Chaque fois qu'une balise ouvrante est rencontrée, le gestionnaire récupère le numéro de ligne actuel avec xml_get_current_line_number() et affiche le nom de l'élément ainsi que sa position de ligne. Enfin, il libère le parseur avec xml_parser_free(). Comme le numéro de ligne est lu pendant le rappel, il reflète la position réelle de chaque élément — contrairement à l'Exemple 1, où la valeur reflète uniquement l'état final après l'analyse complète du document.

Piège courant

xml_get_current_line_number() n'est significatif que pendant l'analyse en cours, ce qui en pratique signifie à l'intérieur d'un gestionnaire d'événements. Si vous l'appelez après que xml_parse() a terminé (comme dans l'Exemple 1), vous obtenez la ligne du dernier octet consommé, et non la ligne d'un élément spécifique. Pour les positions par élément, lisez-le toujours à l'intérieur du gestionnaire comme indiqué dans l'Exemple 2.

Fonctions associées

• xml_get_current_column_number() — la colonne dans la ligne actuelle.
• xml_get_current_byte_index() — le décalage en octets dans le document.
• xml_get_error_code() et xml_error_string() — transformer un échec d'analyse en message lisible.
• xml_set_element_handler() — enregistrer les rappels de balises ouvrantes/fermantes utilisés dans l'Exemple 2.

Conclusion

Dans cet article, nous avons examiné la fonction xml_get_current_line_number() de PHP et la façon dont elle récupère le numéro de ligne actuel d'un parseur XML. Nous avons expliqué ce que fait la fonction, sa syntaxe et sa valeur de retour, et l'avons illustrée aussi bien dans une analyse en une seule fois que dans un gestionnaire SAX en direct. En lisant le numéro de ligne à l'intérieur de vos gestionnaires d'événements, vous pouvez localiser précisément les éléments dans le document source pour le débogage, le rapport d'erreurs et le suivi de la progression.

Pratique