xml_parse_into_struct()

La fonction xml_parse_into_struct() est une fonction PHP intégrée qui analyse des données XML dans un tableau multidimensionnel. Elle appartient à l'extension XML Parser et expose une vue de bas niveau de style SAX d'un document : au lieu de vous fournir un arbre d'objets navigable, elle aplatit le XML en une liste plate d'« événements » (balise ouvrante, données de caractères, balise fermante) que vous pouvez parcourir.

Cette page explique ce que la fonction retourne, sa signature complète, comment lire les deux tableaux de sortie qu'elle remplit ($values et $index), ainsi que deux exemples complets et exécutables.

Assurez-vous que l'extension xml est activée dans votre fichier de configuration php.ini avant d'utiliser cette fonction (elle est intégrée et activée par défaut dans la plupart des builds PHP).

Quand l'utiliser

xml_parse_into_struct() est utile lorsque vous devez parcourir chaque élément d'un document XML dans l'ordre du document — par exemple, pour convertir du XML dans un autre format, pour aplatir des données profondément imbriquées, ou pour analyser la structure d'un fichier.

Pour la plupart des tâches courantes, l'API SimpleXML orientée objet (simplexml_load_string() / simplexml_load_file()) est plus facile à lire. Recourez à xml_parse_into_struct() lorsque vous souhaitez spécifiquement obtenir le tableau linéaire de style événementiel qu'elle produit.

Syntaxe

La signature de la fonction xml_parse_into_struct() est la suivante :

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

Elle retourne 0 en cas d'échec et une valeur non nulle en cas de succès.

La structure de $values

Chaque entrée dans $values décrit un seul événement et possède ces clés :

• tag — le nom de l'élément.
• type — l'un des types suivants : open (balise de début avec enfants), close (balise de fin), complete (élément autonome), ou cdata (données de caractères entre les balises).
• level — la profondeur d'imbrication, commençant à 1.
• value — le contenu textuel, lorsqu'il est présent.
• attributes — un tableau associatif des attributs de l'élément, lorsqu'ils sont présents.

Exemples d'utilisation

Examinons quelques exemples pratiques d'utilisation de xml_parse_into_struct() en PHP. Les deux utilisent ce document 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>

Exemple 1 : Analyse de données XML dans un tableau structuré

Lisez le fichier, analysez-le dans $values et $index, et signalez toute erreur :

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

Ce code crée un analyseur XML à l'aide de xml_parser_create() et désactive le repliage de casse (avec xml_parser_set_option()) afin que les noms de balises conservent leur casse d'origine. Il lit le fichier XML dans $xml_data, initialise des tableaux $values et $index vides, puis appelle xml_parse_into_struct() pour les remplir. En cas d'échec de l'analyse, il récupère le code avec xml_get_error_code(), le convertit en message avec xml_error_string(), et affiche le numéro de ligne. Enfin, il libère l'analyseur avec xml_parser_free().

Après une analyse réussie, $index vous permet d'accéder directement à chaque occurrence d'une balise. Pour le document ci-dessus, il ressemble à ceci :

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

Chaque nombre est un décalage dans $values. Ainsi, $index["title"] vous indique que les deux événements <title> se trouvent aux positions 2 et 9. Vous pouvez l'utiliser pour extraire directement les valeurs :

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

Sortie :

Title: PHP Basics
Title: XML Parsing

Exemple 2 : Analyse de la structure d'un fichier XML

Pour inspecter la forme du document, parcourez $values et réagissez au type de chaque événement. La configuration est identique à l'Exemple 1 ; la nouveauté est la boucle :

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

Cette boucle vérifie le type de chaque événement : "open" affiche une balise de début, "close" affiche une balise de fin. Pour le document exemple, la sortie est :

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

Notez que <title> et <author> n'apparaissent pas ici : comme ils ne contiennent que du texte, ils arrivent sous forme d'événements complete plutôt que de paires open/close séparées. Ajoutez un case "complete" (ou vérifiez $value["value"]) si vous avez besoin de leur contenu également.

Conclusion

La fonction PHP xml_parse_into_struct() aplatit le XML en un tableau linéaire d'événements d'analyse, vous offrant une façon de bas niveau de style SAX pour lire un document. La clé pour bien l'utiliser est de comprendre les deux tableaux de sortie : $values contient les événements ordonnés (chacun avec tag, type, level, value et attributes), et $index associe les noms de balises à leurs positions afin que vous puissiez accéder directement à n'importe quel élément.

Pour naviguer dans du XML structuré dans le code courant, préférez SimpleXML ; pour la vue en flux d'événements présentée ici, xml_parse_into_struct() (ou xml_parse() de niveau inférieur avec des gestionnaires) est l'outil approprié.

Entraînement