xml_get_current_column_number()

La funzione xml_get_current_column_number() è una funzione built-in di PHP che recupera il numero di colonna corrente di un parser XML — l'offset orizzontale dei caratteri (con base 1) all'interno della riga corrente raggiunta dal parser. Appartiene all'estensione legacy XML Parser (Expat), non a SimpleXML o DOM, ed è significativa solo mentre un'analisi è in corso.

Questa pagina illustra cosa restituisce la funzione, la sua sintassi e degli esempi eseguibili che mostrano il numero di colonna riportato dall'interno degli handler SAX. È particolarmente utile per individuare con precisione la posizione di un elemento o di un errore nell'input — ad esempio, per scrivere un messaggio di log preciso o una diagnostica tipo "errore di sintassi vicino alla colonna X".

Poiché il valore riflette la posizione in tempo reale del parser, è necessario chiamarla dall'interno di un handler (o subito dopo che xml_parse() fallisce). Si abbina naturalmente a xml_get_current_line_number() e xml_get_current_byte_index() per descrivere completamente una posizione.

Sintassi

xml_get_current_column_number(XMLParser $parser): int|false

$parser è il parser XML creato da xml_parser_create() (in PHP 8.0+ è un oggetto XMLParser; nelle versioni precedenti era una risorsa). La funzione restituisce il numero di colonna come intero, oppure false se $parser non è un parser valido.

Esempi d'uso

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

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

Supponiamo di avere una stringa XML da analizzare con l'estensione legacy XML Parser in PHP. È possibile chiamare xml_get_current_column_number() all'interno di un handler SAX — registrato con xml_set_element_handler() — per recuperare la colonna in cui inizia ogni tag:

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

Questo codice crea un parser, registra gli handler per i tag di apertura e chiusura, ed esegue xml_parse() sui dati. All'interno dell'handler del tag di apertura, legge il numero di colonna in tempo reale e lo stampa, quindi libera il parser con xml_parser_free(). Si noti che la colonna punta al carattere successivo al simbolo di apertura del tag, quindi avanza man mano che il parser consuma ogni tag. L'output è:

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

Esempio 2: Tracciamento dei numeri di colonna durante l'analisi

Supponiamo di dover tracciare la posizione di colonna del contenuto testuale durante l'analisi di un file XML. Poiché xml_parse_into_struct() non popola i numeri di colonna nel proprio array di output, il tracciamento in tempo reale richiede handler di eventi in stile SAX anziché l'iterazione post-analisi. È possibile registrare un handler per i dati di carattere con xml_set_character_data_handler() per acquisire le posizioni delle colonne man mano che il parser incontra il testo:

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

L'handler per i dati di carattere può essere attivato più volte per nodo di testo (ad esempio, attorno agli spazi bianchi e alle interruzioni di riga), quindi in genere si visualizzano più colonne riportate. Questo approccio traccia le posizioni in tempo reale, a differenza dell'iterazione array post-analisi, che non può accedere allo stato dinamico del parser. L'output per questo input è:

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

Note e avvertenze

• Chiamarla durante l'analisi. Il valore ha senso solo mentre xml_parse() è in esecuzione (all'interno di un handler) o immediatamente dopo un errore di analisi. Al di fuori di quella finestra temporale non ha alcun significato utile.
• Le colonne sono con base 1 e per riga. Il conteggio si azzera ad ogni nuova riga. Combinatela con xml_get_current_line_number() per ottenere una posizione riga:colonna completa.
• Indice di byte vs. colonna. Se è necessario l'offset assoluto dall'inizio del documento anziché la posizione per riga, utilizzare xml_get_current_byte_index().
• Estensione legacy. Il parser XML basato su Expat è procedurale e basato sugli eventi. Per la maggior parte della gestione moderna dei documenti, si preferisce SimpleXML o DOM — ma per l'elaborazione in streaming di file di grandi dimensioni o per posizioni di errore precise, questa estensione è ancora lo strumento giusto.

Conclusione

In questo articolo abbiamo discusso della funzione xml_get_current_column_number() di PHP e di come può essere utilizzata per recuperare il numero di colonna corrente di un parser XML in PHP. Abbiamo spiegato cosa fa la funzione, la sua sintassi e fornito esempi di come può essere utilizzata in scenari pratici. Seguendo questi esempi, è possibile tenere facilmente traccia della posizione corrente di un parser XML durante l'analisi e utilizzarla nelle proprie applicazioni PHP per logging, debug o monitoraggio dell'avanzamento.

Esercitazione