xml_get_current_line_number()

La funzione xml_get_current_line_number() è una funzione built-in di PHP che recupera il numero di riga corrente di un parser XML. Appartiene all'estensione procedurale XML Parser (Expat) e viene utilizzata durante l'analisi XML con le funzioni SAX-style xml_parse*. Conoscere il numero di riga corrente è utile per il debug, la segnalazione degli errori e il monitoraggio dell'avanzamento del parsing.

Questa pagina tratta la sintassi della funzione, il suo valore di ritorno ed esempi pratici — sia con un parsing in una sola chiamata che all'interno di un handler di eventi SAX attivo.

Quando usarla

Chiama xml_get_current_line_number() ogni volta che hai bisogno della posizione del parser nel documento sorgente, tipicamente:

• Segnalazione degli errori — quando un handler di eventi o xml_get_error_code() segnala un problema, il numero di riga indica all'utente dove nel file si è verificato.
• Monitoraggio dell'avanzamento — stampa quale riga viene elaborata durante l'analisi di un file XML di grandi dimensioni.
• Diagnostica — abbinalo a xml_get_current_column_number() e xml_get_current_byte_index() per una posizione precisa riga:colonna.

Questa funzione fa parte dell'API Expat procedurale. Se analizzi XML con la classe orientata agli oggetti XMLReader, usa invece il suo metodo getLineNo().

Sintassi

La sintassi della funzione xml_get_current_line_number() è la seguente:

xml_get_current_line_number($parser): int|false

Parametro

• $parser — il parser XML creato da xml_parser_create() (o xml_parser_create_ns()). In PHP 8+ è un oggetto XMLParser; in PHP 7 e precedenti è una risorsa.

Valore di ritorno

Restituisce il numero di riga corrente (un int, a partire dalla riga 1) mentre il parser legge il documento. Restituisce false se $parser non è un parser valido. Durante il parsing, il valore riflette la riga dei dati raggiunta dal parser — quindi è più significativo quando viene letto all'interno di un handler di eventi.

Esempi d'uso

Vediamo alcuni esempi pratici di utilizzo di xml_get_current_line_number() in PHP.

Esempio 1: Recupero del numero di riga corrente di un parser XML

Supponiamo di avere un file XML data.xml che si desidera analizzare usando l'estensione XML Parser in PHP. È possibile usare la funzione xml_get_current_line_number() per recuperare il numero di riga raggiunto dopo il parsing, in questo modo:

$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);

Questo codice crea un parser XML usando xml_parser_create() e imposta un'opzione per disattivare il case folding. Usa quindi xml_parse_into_struct() per analizzare il file XML data.xml e memorizzare il risultato nell'array $values. Recupera il numero di riga corrente con xml_get_current_line_number(), che restituisce il numero di riga dell'ultimo elemento analizzato, e lo stampa nella console. Infine, libera la memoria usata dal parser XML con xml_parser_free().

Esempio 2: Monitoraggio dei numeri di riga durante il parsing SAX

Supponiamo di voler monitorare il numero di riga di ogni elemento mentre viene analizzato tramite un handler di eventi SAX. È possibile usare xml_set_element_handler() insieme a xml_get_current_line_number() per monitorare la posizione del parser in tempo reale, in questo modo:

$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);

Questo codice crea un parser XML usando xml_parser_create() e registra un handler di elementi con xml_set_element_handler(). Usa poi xml_parse() per analizzare il file XML data.xml. Ogni volta che viene incontrato un tag di apertura, l'handler recupera il numero di riga corrente con xml_get_current_line_number() e restituisce il nome dell'elemento insieme alla sua posizione di riga. Infine, libera il parser con xml_parser_free(). Poiché il numero di riga viene letto durante il callback, riflette la posizione reale di ciascun elemento — a differenza dell'Esempio 1, dove il valore riflette solo lo stato finale dopo l'analisi dell'intero documento.

Errore comune

xml_get_current_line_number() è significativa solo mentre il parsing è in corso, il che nella pratica significa all'interno di un handler di eventi. Se la chiami dopo che xml_parse() ha terminato (come nell'Esempio 1), ottieni la riga dell'ultimo byte consumato, non la riga di un elemento specifico. Per le posizioni per elemento, leggila sempre all'interno dell'handler come mostrato nell'Esempio 2.

Funzioni correlate

• xml_get_current_column_number() — la colonna all'interno della riga corrente.
• xml_get_current_byte_index() — l'offset in byte nel documento.
• xml_get_error_code() e xml_error_string() — trasformano un errore di parsing in un messaggio leggibile.
• xml_set_element_handler() — registra i callback per i tag di apertura/chiusura usati nell'Esempio 2.

Conclusione

In questo articolo abbiamo discusso la funzione xml_get_current_line_number() di PHP e come recupera il numero di riga corrente di un parser XML. Abbiamo trattato cosa fa la funzione, la sua sintassi e il valore di ritorno, e l'abbiamo mostrata sia in un parsing in una sola chiamata che in un handler SAX attivo. Leggendo il numero di riga all'interno degli handler di eventi, è possibile individuare con precisione gli elementi nel documento sorgente per il debug, la segnalazione degli errori e il monitoraggio dell'avanzamento.

Pratica