xml_parse_into_struct()

La función xml_parse_into_struct() es una función integrada de PHP que analiza datos XML en un array multidimensional. Pertenece a la extensión XML Parser y expone una vista de bajo nivel del documento al estilo SAX: en lugar de proporcionarte un árbol de objetos navegable, aplana el XML en una lista plana de "eventos" (etiqueta de apertura, datos de carácter, etiqueta de cierre) que puedes iterar.

Esta página cubre lo que devuelve la función, su firma completa, cómo leer los dos arrays de salida que rellena ($values y $index), y dos ejemplos completos y ejecutables.

Asegúrate de que la extensión xml esté habilitada en tu configuración php.ini antes de usar esta función (viene incluida y habilitada por defecto en la mayoría de las instalaciones de PHP).

Cuándo usarla

xml_parse_into_struct() es útil cuando necesitas recorrer cada elemento de un documento XML en orden de documento — por ejemplo, para convertir XML a otro formato, para aplanar datos profundamente anidados o para analizar la estructura de un archivo.

Para la mayoría de las tareas cotidianas, la API orientada a objetos de SimpleXML (simplexml_load_string() / simplexml_load_file()) es más fácil de leer. Recurre a xml_parse_into_struct() cuando necesites específicamente el array lineal al estilo de eventos que produce.

Sintaxis

La firma de la función xml_parse_into_struct() es la siguiente:

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

Devuelve 0 en caso de error y un valor distinto de cero en caso de éxito.

La estructura de $values

Cada entrada en $values describe un único evento y tiene estas claves:

• tag — el nombre del elemento.
• type — uno de open (etiqueta de apertura con hijos), close (etiqueta de cierre), complete (un elemento autocontenido) o cdata (datos de carácter entre etiquetas).
• level — la profundidad de anidamiento, comenzando en 1.
• value — el contenido de texto, cuando está presente.
• attributes — un array asociativo de los atributos del elemento, cuando está presente.

Ejemplos de uso

Veamos algunos ejemplos prácticos del uso de xml_parse_into_struct() en PHP. Ambos usan este 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>

Ejemplo 1: Analizar datos XML en un array estructurado

Lee el archivo, analízalo en $values y $index, e informa de cualquier error:

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

Este código crea un analizador XML usando xml_parser_create() y deshabilita el plegado de mayúsculas (con xml_parser_set_option()) para que los nombres de etiqueta conserven su caso original. Lee el archivo XML en $xml_data, inicializa los arrays vacíos $values y $index, y luego llama a xml_parse_into_struct() para rellenarlos. Si el análisis falla, recupera el código con xml_get_error_code(), lo convierte en un mensaje con xml_error_string() e imprime el número de línea. Finalmente libera el analizador con xml_parser_free().

Después de un análisis exitoso, $index te permite saltar directamente a cada ocurrencia de una etiqueta. Para el documento anterior tiene este aspecto:

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

Cada número es un desplazamiento dentro de $values. Así, $index["title"] te indica que los dos eventos <title> están en las posiciones 2 y 9. Puedes usarlo para extraer valores directamente:

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

Salida:

Title: PHP Basics
Title: XML Parsing

Ejemplo 2: Analizar la estructura de un archivo XML

Para inspeccionar la forma del documento, itera sobre $values y reacciona al type de cada evento. La configuración es la misma que en el Ejemplo 1; la parte nueva es el bucle:

$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/>";
  }
}

Este bucle comprueba el type de cada evento: "open" imprime una etiqueta de apertura y "close" imprime una etiqueta de cierre. Para el documento de ejemplo produce:

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

Ten en cuenta que <title> y <author> no aparecen aquí: como solo contienen texto, llegan como eventos complete en lugar de pares separados open/close. Agrega un case "complete" (o comprueba $value["value"]) si también necesitas su contenido.

Conclusión

La función xml_parse_into_struct() de PHP aplana el XML en un array lineal de eventos de análisis, dándote una forma de bajo nivel al estilo SAX para leer un documento. La clave para usarla bien es entender los dos arrays de salida: $values contiene los eventos ordenados (cada uno con tag, type, level, value y attributes), y $index mapea los nombres de etiqueta a sus posiciones para que puedas llegar a cualquier elemento directamente.

Para navegar XML estructurado en el código cotidiano, prefiere SimpleXML; para la vista de flujo de eventos mostrada aquí, xml_parse_into_struct() (o el xml_parse() de nivel inferior con manejadores) es la herramienta adecuada.

Práctica