xml_parse_into_struct()

La funzione xml_parse_into_struct() è una funzione built-in di PHP che analizza dati XML in un array multidimensionale. Appartiene all'estensione XML Parser e fornisce una vista SAX-style a basso livello di un documento: invece di restituire un albero di oggetti navigabile, appiattisce l'XML in un elenco piatto di "eventi" (tag di apertura, dati carattere, tag di chiusura) su cui è possibile iterare.

Questa pagina illustra cosa restituisce la funzione, la sua firma completa, come leggere i due array di output che riempie ($values e $index), e due esempi completi ed eseguibili.

Assicurati che l'estensione xml sia abilitata nella configurazione php.ini prima di usare questa funzione (è inclusa e abilitata per impostazione predefinita nella maggior parte delle build PHP).

Quando usarla

xml_parse_into_struct() è utile quando occorre percorrere ogni elemento di un documento XML nell'ordine del documento — ad esempio per convertire XML in un altro formato, per appiattire dati profondamente annidati o per analizzare la struttura di un file.

Per la maggior parte dei compiti quotidiani, l'API orientata agli oggetti SimpleXML (simplexml_load_string() / simplexml_load_file()) è più leggibile. Usa xml_parse_into_struct() quando desideri specificamente l'array lineare in stile evento che produce.

Sintassi

La firma della funzione xml_parse_into_struct() è la seguente:

xml_parse_into_struct($parser, $data, &$values, &$index): int

Restituisce 0 in caso di errore e un valore diverso da zero in caso di successo.

La struttura di $values

Ogni voce in $values descrive un singolo evento e ha le seguenti chiavi:

• tag — il nome dell'elemento.
• type — uno tra open (tag di apertura con figli), close (tag di chiusura), complete (elemento autonomo), o cdata (dati carattere tra i tag).
• level — la profondità di annidamento, a partire da 1.
• value — il contenuto testuale, se presente.
• attributes — un array associativo degli attributi dell'elemento, se presenti.

Esempi di utilizzo

Vediamo alcuni esempi pratici dell'uso di xml_parse_into_struct() in PHP. Entrambi utilizzano questo documento data.xml:

<?xml version="1.0"?>
<library>
  <book>
    <title>PHP Basics</title>
    <author>Jane Doe</author>
  </book>
  <book>
    <title>XML Parsing</title>
    <author>John Smith</author>
  </book>
</library>

Esempio 1: Analisi di dati XML in un array strutturato

Leggi il file, analizzalo in $values e $index, e segnala eventuali errori:

$xml_parser = xml_parser_create();
xml_parser_set_option($xml_parser, XML_OPTION_CASE_FOLDING, 0);
$xml_data = file_get_contents("data.xml");
$values = array();
$index = array();
if (!xml_parse_into_struct($xml_parser, $xml_data, $values, $index)) {
  $error_message = xml_error_string(xml_get_error_code($xml_parser));
  $error_line = xml_get_current_line_number($xml_parser);
  echo "XML Parsing Error: $error_message at line $error_line";
}
xml_parser_free($xml_parser);

Questo codice crea un parser XML con xml_parser_create() e disabilita il case folding (tramite xml_parser_set_option()) in modo che i nomi dei tag mantengano la maiuscola originale. Legge il file XML in $xml_data, inizializza gli array vuoti $values e $index, quindi chiama xml_parse_into_struct() per popolarli. Se il parsing fallisce, recupera il codice con xml_get_error_code(), lo converte in un messaggio con xml_error_string(), e stampa il numero di riga. Infine rilascia il parser con xml_parser_free().

Dopo un'analisi riuscita, $index consente di accedere direttamente a ogni occorrenza di un tag. Per il documento precedente ha questo aspetto:

// $index
[
  "library" => [0, 7, 14, 15],
  "book"    => [1, 3, 5, 6, 8, 10, 12, 13],
  "title"   => [2, 9],
  "author"  => [4, 11],
]

Ogni numero è un offset in $values. Quindi $index["title"] indica che i due eventi <title> si trovano nelle posizioni 2 e 9. Puoi usarlo per estrarre i valori direttamente:

foreach ($index["title"] as $i) {
  echo "Title: " . $values[$i]["value"] . "\n";
}

Output:

Title: PHP Basics
Title: XML Parsing

Esempio 2: Analisi della struttura di un file XML

Per ispezionare la forma del documento, itera su $values e reagisci al type di ogni evento. La configurazione è la stessa dell'Esempio 1; la parte nuova è il ciclo:

$xml_parser = xml_parser_create();
xml_parser_set_option($xml_parser, XML_OPTION_CASE_FOLDING, 0);
$xml_data = file_get_contents("data.xml");
$values = array();
$index = array();
if (!xml_parse_into_struct($xml_parser, $xml_data, $values, $index)) {
  $error_message = xml_error_string(xml_get_error_code($xml_parser));
  $error_line = xml_get_current_line_number($xml_parser);
  echo "XML Parsing Error: $error_message at line $error_line";
}
xml_parser_free($xml_parser);

foreach ($values as $value) {
  if ($value["type"] == "open") {
    echo "Start element: " . $value["tag"] . "<br/>";
  } else if ($value["type"] == "close") {
    echo "End element: " . $value["tag"] . "<br/>";
  }
}

Questo ciclo controlla il type di ogni evento: "open" stampa un tag di apertura, "close" stampa un tag di chiusura. Per il documento di esempio produce:

Start element: library
Start element: book
End element: book
Start element: book
End element: book
End element: library

Nota che <title> e <author> non compaiono qui: poiché contengono solo testo, arrivano come eventi complete invece che come coppie separate open/close. Aggiungi un case "complete" (o controlla $value["value"]) se hai bisogno anche del loro contenuto.

Conclusione

La funzione xml_parse_into_struct() di PHP appiattisce l'XML in un array lineare di eventi di parsing, fornendo un modo a basso livello in stile SAX per leggere un documento. La chiave per usarla bene è comprendere i due array di output: $values contiene gli eventi ordinati (ognuno con tag, type, level, value e attributes), mentre $index mappa i nomi dei tag alle loro posizioni in modo da poter raggiungere qualsiasi elemento direttamente.

Per navigare XML strutturato nel codice quotidiano, preferisci SimpleXML; per la vista a flusso di eventi mostrata qui, xml_parse_into_struct() (o il più basso livello xml_parse() con gestori) è lo strumento giusto.

Esercitazione