xml_parse_into_struct()

A função xml_parse_into_struct() é uma função nativa do PHP que analisa dados XML em um array multidimensional. Ela pertence à extensão XML Parser e expõe uma visão de baixo nível e estilo SAX de um documento: em vez de fornecer uma árvore de objetos navegável, ela achata o XML em uma lista plana de "eventos" (abertura de tag, dados de caracteres, fechamento de tag) pelos quais você pode iterar.

Esta página aborda o que a função retorna, sua assinatura completa, como ler os dois arrays de saída que ela preenche ($values e $index), e dois exemplos completos e executáveis.

Certifique-se de que a extensão xml esteja habilitada no seu arquivo php.ini antes de usar esta função (ela é incluída e habilitada por padrão na maioria das compilações do PHP).

Quando usar

xml_parse_into_struct() é útil quando você precisa percorrer cada elemento de um documento XML na ordem do documento — por exemplo, para converter XML em outro formato, para achatar dados profundamente aninhados, ou para analisar a estrutura de um arquivo.

Para a maioria das tarefas cotidianas, a API orientada a objetos SimpleXML (simplexml_load_string() / simplexml_load_file()) é mais fácil de ler. Use xml_parse_into_struct() quando você precisar especificamente do array linear no estilo de eventos que ela produz.

Sintaxe

A assinatura da função xml_parse_into_struct() é a seguinte:

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

Retorna 0 em caso de falha e um valor diferente de zero em caso de sucesso.

A estrutura de $values

Cada entrada em $values descreve um único evento e possui as seguintes chaves:

• tag — o nome do elemento.
• type — um dos valores: open (tag de abertura com filhos), close (tag de fechamento), complete (um elemento autossuficiente) ou cdata (dados de caracteres entre tags).
• level — a profundidade de aninhamento, começando em 1.
• value — o conteúdo de texto, quando presente.
• attributes — um array associativo dos atributos do elemento, quando presente.

Exemplos de uso

Vejamos alguns exemplos práticos do uso de xml_parse_into_struct() em PHP. Ambos utilizam 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>

Exemplo 1: Analisando dados XML em um array estruturado

Leia o arquivo, analise-o em $values e $index, e reporte qualquer erro:

$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 cria um analisador XML usando xml_parser_create() e desabilita o dobramento de maiúsculas/minúsculas (com xml_parser_set_option()) para que os nomes das tags mantenham seu caso original. Ele lê o arquivo XML em $xml_data, inicializa arrays $values e $index vazios, e então chama xml_parse_into_struct() para preenchê-los. Se a análise falhar, ele recupera o código com xml_get_error_code(), transforma-o em uma mensagem com xml_error_string(), e imprime o número da linha. Por fim, libera o analisador com xml_parser_free().

Após uma análise bem-sucedida, $index permite que você acesse diretamente cada ocorrência de uma tag. Para o documento acima, ele tem esta aparência:

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

Cada número é um deslocamento em $values. Portanto, $index["title"] indica que os dois eventos <title> estão nas posições 2 e 9. Você pode usar isso para obter valores diretamente:

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

Saída:

Title: PHP Basics
Title: XML Parsing

Exemplo 2: Analisando a estrutura de um arquivo XML

Para inspecionar a forma do documento, itere sobre $values e reaja ao type de cada evento. A configuração é a mesma do Exemplo 1; a parte nova é o loop:

$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 loop verifica o type de cada evento: "open" imprime uma tag de abertura, "close" imprime uma tag de fechamento. Para o documento de exemplo, a saída é:

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

Observe que <title> e <author> não aparecem aqui: como contêm apenas texto, chegam como eventos complete em vez de pares separados open/close. Adicione um case "complete" (ou verifique $value["value"]) se você precisar do conteúdo deles também.

Conclusão

A função xml_parse_into_struct() do PHP achata XML em um array linear de eventos de análise, fornecendo uma maneira de baixo nível e estilo SAX para ler um documento. A chave para usá-la bem é compreender os dois arrays de saída: $values contém os eventos ordenados (cada um com tag, type, level, value e attributes), e $index mapeia nomes de tags para suas posições para que você possa acessar qualquer elemento diretamente.

Para navegar em XML estruturado em código cotidiano, prefira o SimpleXML; para a visão de fluxo de eventos mostrada aqui, xml_parse_into_struct() (ou o xml_parse() de nível mais baixo com handlers) é a ferramenta certa.

Prática