xml_get_current_byte_index()

La fonction xml_get_current_byte_index() est une fonction PHP intégrée qui retourne le nombre d'octets du document XML déjà consommés par l'analyseur. Elle fait partie de l'extension historique XML Parser, qui analyse les documents en mode flux, de style SAX : au lieu de charger l'intégralité du document dans un arbre, elle déclenche des callbacks au fur et à mesure de son parcours du balisage. Cette fonction vous indique où se trouve l'analyseur lorsque l'un de ces callbacks s'exécute.

Vous l'appelez généralement depuis l'intérieur d'un gestionnaire enregistré avec xml_set_element_handler() ou xml_set_character_data_handler(). Elle est particulièrement utile pour signaler la progression de l'analyse sur un grand fichier, ou pour localiser l'emplacement dans la source d'un élément ou d'un contenu particulier — par exemple, pour créer un message d'erreur pointant vers un décalage d'octet.

Cette page couvre la syntaxe de la fonction, sa valeur de retour, deux exemples pratiques ainsi que les pièges à éviter.

Syntaxe

xml_get_current_byte_index(XMLParser $parser): int

Paramètres

• $parser — le handle de l'analyseur retourné par xml_parser_create() ou xml_parser_create_ns(). Avec PHP 8.0+, il s'agit d'un objet XMLParser ; avec PHP 7.x, c'est une resource.

Valeur de retour

Retourne le décalage en octets (un entier à base zéro) de la position actuelle de l'analyseur dans le document. Comme il compte des octets et non des caractères, un fichier UTF-8 multi-octet rapportera un index plus grand que son nombre de caractères. Si vous avez besoin d'un numéro de ligne ou de colonne à la place, utilisez les fonctions complémentaires xml_get_current_line_number() et xml_get_current_column_number().

La valeur n'a de sens que pendant l'analyse en cours (c'est-à-dire à l'intérieur d'un gestionnaire). L'appeler avant que xml_parse() ait démarré retourne 0.

Exemples d'utilisation

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

Exemple 1 : Récupérer l'index d'octet courant d'un analyseur XML

Supposons que vous ayez un fichier XML "data.xml" que vous souhaitez analyser à l'aide de l'extension XML Parser en PHP. Vous pouvez utiliser la fonction xml_get_current_byte_index() à l'intérieur d'un gestionnaire d'éléments SAX pour récupérer l'index d'octet courant lorsqu'un élément commence, comme ceci :

Récupérer l'index d'octet courant d'un analyseur XML en PHP

$parser = xml_parser_create();
xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, 0);

function start_handler($parser, $name, $attrs) {
    $byte_index = xml_get_current_byte_index($parser);
    echo "Element <$name> starts at byte index: $byte_index\n";
}

xml_set_element_handler($parser, "start_handler", null);

$xml_data = file_get_contents("data.xml");
xml_parse($parser, $xml_data, true);
xml_parser_free($parser);

Ce code crée un analyseur XML à l'aide de xml_parser_create(), et définit une option pour désactiver le repliement de casse. Il définit un callback start_handler qui appelle xml_get_current_byte_index() pour obtenir la position de l'analyseur chaque fois qu'un élément commence. Le gestionnaire est enregistré avec xml_set_element_handler(), et xml_parse() traite le fichier. Enfin, il libère la mémoire utilisée par l'analyseur XML à l'aide de xml_parser_free().

Exemple 2 : Suivre la progression de l'analyse

Supposons que vous ayez un grand fichier XML et que vous souhaitiez afficher un indicateur de progression pendant son analyse. Vous pouvez utiliser l'extension XML Parser avec un gestionnaire de données de caractères pour suivre l'index d'octet au fur et à mesure que l'analyseur parcourt le fichier, comme ceci :

Suivre la progression de l'analyse en PHP

$parser = xml_parser_create();
xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, 0);

$total_bytes = filesize("data.xml");
$last_reported = 0;

function progress_handler($parser, $data) {
    global $last_reported, $total_bytes;
    $current = xml_get_current_byte_index($parser);
    if ($current - $last_reported > 1024) { // Report every 1KB
        $progress = round(($current / $total_bytes) * 100);
        echo "Parsing progress: $progress%\n";
        $last_reported = $current;
    }
}

xml_set_character_data_handler($parser, "progress_handler");
xml_parse($parser, file_get_contents("data.xml"), true);
xml_parser_free($parser);

Ce code crée un analyseur XML et calcule la taille totale du fichier. Il définit un callback progress_handler qui compare l'index d'octet courant à la dernière position rapportée. Si plus de 1 Ko a été lu, il calcule et affiche le pourcentage d'analyse. Le gestionnaire est enregistré avec xml_set_character_data_handler(), et xml_parse() traite le fichier. Enfin, il libère la mémoire utilisée par l'analyseur XML à l'aide de xml_parser_free().

Notes et pièges

• Octets, pas caractères. Sur un document UTF-8 avec des caractères multi-octets, le décalage retourné peut être plus grand que la position en caractères. Ne le traitez pas comme un nombre de caractères.
• Appelez-le à l'intérieur d'un gestionnaire. L'index d'octet ne reflète une position réelle que pendant l'exécution d'un callback. En dehors de l'analyse, il retourne 0.
• Le décalage peut pointer légèrement au-delà du balisage. En fonction de la mise en mémoire tampon de libexpat, l'index rapporté peut se situer à la fin du token qui a déclenché le callback plutôt qu'à son début exact. Utilisez-le pour la progression approximative et la localisation, pas pour un découpage précis à l'octet.
• Il s'agit de l'API SAX historique. Pour la plupart des nouveaux codes, les extensions SimpleXML ou DOM basées sur des arbres sont plus simples. Utilisez l'extension XML Parser uniquement lorsque vous avez spécifiquement besoin du streaming pour des fichiers très volumineux. Consultez la vue d'ensemble des analyseurs XML PHP pour choisir.

Conclusion

Dans cet article, nous avons présenté la fonction xml_get_current_byte_index() de PHP et la façon dont elle peut être utilisée pour récupérer l'index d'octet courant d'un analyseur XML lors d'une analyse de style SAX. 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 de l'analyseur et l'utiliser dans vos applications PHP pour surveiller la progression ou localiser des éléments spécifiques.

Pratique