xml_parse_into_struct()

Die Funktion xml_parse_into_struct() ist eine in PHP integrierte Funktion, die XML-Daten in ein mehrdimensionales Array umwandelt. Sie gehört zur XML-Parser-Erweiterung und bietet eine SAX-artige, low-level-Ansicht eines Dokuments: Anstatt einen navigierbaren Objektbaum zurückzugeben, flacht sie das XML in eine flache Liste von „Ereignissen" ab (öffnendes Tag, Zeichendaten, schließendes Tag), über die Sie iterieren können.

Diese Seite erklärt, was die Funktion zurückgibt, ihre vollständige Signatur, wie die beiden Ausgabe-Arrays ($values und $index) zu lesen sind, und enthält zwei vollständige, ausführbare Beispiele.

Stellen Sie sicher, dass die xml-Erweiterung in Ihrer php.ini-Konfiguration aktiviert ist, bevor Sie diese Funktion verwenden (sie ist in den meisten PHP-Builds gebündelt und standardmäßig aktiviert).

Wann verwenden

xml_parse_into_struct() ist nützlich, wenn Sie jedes Element eines XML-Dokuments in Dokumentreihenfolge durchlaufen müssen — beispielsweise um XML in ein anderes Format zu konvertieren, tief verschachtelte Daten abzuflachen oder die Struktur einer Datei zu analysieren.

Für die meisten alltäglichen Aufgaben ist die objektorientierte SimpleXML-API (simplexml_load_string() / simplexml_load_file()) einfacher zu lesen. Greifen Sie auf xml_parse_into_struct() zurück, wenn Sie speziell das lineare, ereignisartige Array benötigen, das sie erzeugt.

Syntax

Die Signatur der Funktion xml_parse_into_struct() lautet wie folgt:

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

Sie gibt bei einem Fehler 0 zurück und bei Erfolg einen Wert ungleich null.

Die Struktur von $values

Jeder Eintrag in $values beschreibt ein einzelnes Ereignis und enthält folgende Schlüssel:

• tag — der Elementname.
• type — eines von open (startendes Tag mit Kindknoten), close (schließendes Tag), complete (ein eigenständiges Element) oder cdata (Zeichendaten zwischen Tags).
• level — die Verschachtelungstiefe, beginnend bei 1.
• value — der Textinhalt, sofern vorhanden.
• attributes — ein assoziatives Array der Attribute des Elements, sofern vorhanden.

Verwendungsbeispiele

Betrachten wir einige praktische Beispiele zur Verwendung von xml_parse_into_struct() in PHP. Beide verwenden dieses data.xml-Dokument:

<?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>

Beispiel 1: XML-Daten in ein strukturiertes Array parsen

Die Datei lesen, in $values und $index parsen und etwaige Fehler melden:

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

Dieser Code erstellt einen XML-Parser mit xml_parser_create() und deaktiviert die Groß-/Kleinschreibungsanpassung (mit xml_parser_set_option()), damit Tag-Namen ihre ursprüngliche Schreibweise behalten. Er liest die XML-Datei in $xml_data, initialisiert leere $values- und $index-Arrays und ruft dann xml_parse_into_struct() auf, um sie zu befüllen. Schlägt das Parsen fehl, wird der Code mit xml_get_error_code() abgerufen, mit xml_error_string() in eine Meldung umgewandelt und die Zeilennummer ausgegeben. Schließlich wird der Parser mit xml_parser_free() freigegeben.

Nach einem erfolgreichen Parsen ermöglicht $index das direkte Springen zu jedem Vorkommen eines Tags. Für das obige Dokument sieht es so aus:

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

Jede Zahl ist ein Offset in $values. $index["title"] zeigt also, dass die beiden <title>-Ereignisse an den Positionen 2 und 9 liegen. Sie können das nutzen, um Werte direkt abzurufen:

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

Ausgabe:

Title: PHP Basics
Title: XML Parsing

Beispiel 2: Die Struktur einer XML-Datei analysieren

Um die Form des Dokuments zu untersuchen, iterieren Sie über $values und reagieren auf den type jedes Ereignisses. Die Einrichtung ist dieselbe wie in Beispiel 1; der neue Teil ist die Schleife:

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

Diese Schleife prüft den type jedes Ereignisses: "open" gibt ein öffnendes Tag aus, "close" ein schließendes Tag. Für das Beispieldokument ergibt sich folgende Ausgabe:

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

Beachten Sie, dass <title> und <author> hier nicht erscheinen: Da sie nur Text enthalten, kommen sie als complete-Ereignisse an und nicht als separate open/close-Paare. Fügen Sie einen case "complete" hinzu (oder prüfen Sie $value["value"]), wenn Sie deren Inhalt ebenfalls benötigen.

Fazit

PHPs Funktion xml_parse_into_struct() flacht XML in ein lineares Array von Parse-Ereignissen ab und bietet so eine low-level, SAX-artige Möglichkeit, ein Dokument zu lesen. Der Schlüssel zur effizienten Nutzung liegt im Verständnis der beiden Ausgabe-Arrays: $values enthält die geordneten Ereignisse (jeweils mit tag, type, level, value und attributes), und $index bildet Tag-Namen auf ihre Positionen ab, sodass Sie jedes Element direkt erreichen können.

Für die Navigation in strukturiertem XML im alltäglichen Code bevorzugen Sie SimpleXML; für die hier gezeigte Event-Stream-Ansicht ist xml_parse_into_struct() (oder das low-level xml_parse() mit Handlern) das richtige Werkzeug.

Übung