xml_get_current_byte_index()

La funzione xml_get_current_byte_index() è una funzione PHP integrata che restituisce quanti byte del documento XML il parser ha già consumato. Fa parte dell'estensione legacy XML Parser, che analizza i documenti in modalità streaming SAX-style: invece di caricare l'intero documento in un albero, attiva dei callback mentre scorre il markup. Questa funzione indica dove si trova il parser quando uno di questi callback viene eseguito.

Di solito viene chiamata dall'interno di un handler registrato con xml_set_element_handler() o xml_set_character_data_handler(). È particolarmente utile per segnalare l'avanzamento dell'analisi su un file di grandi dimensioni, o per individuare la posizione nel sorgente in cui è apparso un determinato elemento o contenuto — ad esempio, per costruire un messaggio di errore che indichi un offset di byte.

Questa pagina tratta la sintassi della funzione, il valore restituito, due esempi pratici e le insidie da tenere a mente.

Sintassi

xml_get_current_byte_index(XMLParser $parser): int

Parametri

• $parser — l'handle del parser restituito da xml_parser_create() o xml_parser_create_ns(). In PHP 8.0+ è un oggetto XMLParser; in PHP 7.x è una resource.

Valore restituito

Restituisce l'offset in byte (un intero a base zero) della posizione corrente del parser nel documento. Poiché conta i byte, non i caratteri, un file UTF-8 multibyte riporterà un indice maggiore del numero di caratteri. Se hai bisogno del numero di riga o di colonna, usa le funzioni complementari xml_get_current_line_number() e xml_get_current_column_number().

Il valore è significativo solo mentre l'analisi è in corso (cioè all'interno di un handler). Chiamarla prima che xml_parse() sia avviata restituisce 0.

Esempi d'uso

Vediamo alcuni esempi pratici dell'utilizzo di xml_get_current_byte_index() in PHP.

Esempio 1: Recuperare l'indice del byte corrente di un parser XML

Supponiamo di avere un file XML "data.xml" che si vuole analizzare utilizzando l'estensione XML Parser in PHP. È possibile usare la funzione xml_get_current_byte_index() all'interno di un handler SAX per recuperare l'indice del byte corrente quando inizia un elemento, in questo modo:

Recupero dell'indice del byte corrente di un parser XML in 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);

Questo codice crea un parser XML usando xml_parser_create() e imposta un'opzione per disabilitare il case folding. Definisce un callback start_handler che chiama xml_get_current_byte_index() per ottenere la posizione del parser ogni volta che inizia un elemento. L'handler viene registrato con xml_set_element_handler(), e xml_parse() elabora il file. Infine, libera la memoria usata dal parser XML con xml_parser_free().

Esempio 2: Monitorare l'avanzamento dell'analisi

Supponiamo di avere un file XML di grandi dimensioni e di voler visualizzare un indicatore di avanzamento durante l'analisi. È possibile usare l'estensione XML Parser con un handler per i dati carattere per tracciare l'indice del byte man mano che il parser legge il file, in questo modo:

Monitoraggio dell'avanzamento dell'analisi in 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);

Questo codice crea un parser XML e calcola la dimensione totale del file. Definisce un callback progress_handler che confronta l'indice del byte corrente con l'ultima posizione segnalata. Se sono stati letti più di 1KB, calcola e stampa la percentuale di avanzamento. L'handler viene registrato con xml_set_character_data_handler(), e xml_parse() elabora il file. Infine, libera la memoria usata dal parser XML con xml_parser_free().

Note e avvertenze

• Byte, non caratteri. In un documento UTF-8 con caratteri multibyte, l'offset restituito può essere maggiore della posizione in caratteri. Non trattarlo come un conteggio di caratteri.
• Chiamala all'interno di un handler. L'indice del byte riflette una posizione reale solo mentre è in esecuzione un callback. Al di fuori dell'analisi restituisce 0.
• L'offset può puntare leggermente oltre il markup. A causa del buffering di libexpat, l'indice riportato può trovarsi alla fine del token che ha attivato il callback anziché al suo inizio esatto. Usarlo per il monitoraggio approssimativo dell'avanzamento e la localizzazione, non per un'estrazione byte per byte.
• Questa è l'API SAX legacy. Per la maggior parte del nuovo codice, le estensioni basate su albero SimpleXML o DOM sono più semplici. Ricorrere all'estensione XML Parser quando si ha specificamente bisogno dello streaming per file molto grandi. Consulta la panoramica dei parser XML PHP per scegliere.

Conclusione

In questo articolo abbiamo discusso la funzione xml_get_current_byte_index() di PHP e come può essere usata per recuperare l'indice del byte corrente di un parser XML durante l'analisi SAX-style. Abbiamo spiegato cosa fa la funzione, la sua sintassi e fornito esempi del suo utilizzo in scenari pratici. Seguendo questi esempi, puoi facilmente tracciare la posizione del parser e utilizzarla nelle tue applicazioni PHP per monitorare l'avanzamento o individuare elementi specifici.

Pratica