xml_get_error_code()

Die Funktion xml_get_error_code() ist eine in PHP eingebaute Funktion, die den Fehlercode eines XML-Parsers abruft. Beim Parsen von XML mit der XML-Parser-(Expat)-Erweiterung von PHP geben die Parse-Funktionen false zurück, sobald etwas schiefläuft – aber false allein verrät nicht was schiefgelaufen ist. xml_get_error_code() gibt einen numerischen Code zurück, der den zuletzt aufgetretenen Fehler beschreibt. Diesen Code können Sie mit xml_error_string() in eine menschenlesbare Meldung umwandeln.

Diese Seite behandelt die Syntax der Funktion, ihre Rückgabewerte, die Umwandlung des Codes in eine Meldung sowie die häufigste Fehlerquelle: Der zurückgegebene Code ist ein Expat-Fehlercode, nicht die XML_OPTION_*-Konstante, die man vielleicht erwartet.

Syntax

xml_get_error_code(XMLParser $parser): int

$parser ist der Parser, der mit xml_parser_create() (oder xml_parser_create_ns()) erstellt wurde. In PHP 8.0+ ist dies ein XMLParser-Objekt; in PHP 7.x und früher war es eine resource. Der Code in diesem Kapitel funktioniert mit beiden.

Rückgabewert

Die Funktion gibt einen ganzzahligen Fehlercode zurück:

• 0 (die Konstante XML_ERROR_NONE) bedeutet kein Fehler – das Parsen war erfolgreich.
• Jeder Wert ungleich null identifiziert die Art des Fehlers. Übergeben Sie ihn an xml_error_string(), um eine lesbare Beschreibung zu erhalten, und an xml_get_current_line_number(), um die Fehlerposition zu ermitteln.

Prüfen Sie immer zuerst den Rückgabewert der Parse-Funktion (xml_parse() / xml_parse_into_struct()); rufen Sie xml_get_error_code() nur dann auf, wenn sie false zurückgibt.

Ein vollständiges, ausführbares Beispiel

Das folgende Beispiel parst einen absichtlich fehlerhaften XML-String (das schließende Tag stimmt nicht mit dem öffnenden überein), gibt dann den Fehlercode, die zugehörige Meldung und die Zeilennummer aus. Da das XML als String eingebettet ist, können Sie es direkt kopieren und ausführen – es wird keine Datei benötigt.

<?php
$broken = "<note><to>Ann</from></note>";   // </from> should be </to>

$parser = xml_parser_create();
if (!xml_parse_into_struct($parser, $broken, $values)) {
    $code = xml_get_error_code($parser);
    echo "Error code:  $code\n";
    echo "Message:     " . xml_error_string($code) . "\n";
    echo "On line:     " . xml_get_current_line_number($parser) . "\n";
}
xml_parser_free($parser);

Ausgabe:

Error code:  76
Message:     Mismatched tag
On line:     1

xml_parse_into_struct() gibt false zurück, daher rufen wir xml_get_error_code() auf und übergeben das Ergebnis direkt an xml_error_string(), um die Meldung „Mismatched tag" zu erhalten.

Der häufige Fehler: Der Code ist ein Expat-Code

Es ist verlockend, das Ergebnis in einem switch gegen Konstanten wie XML_ERROR_TAG_MISMATCH zu vergleichen:

switch ($code) {
    case XML_ERROR_TAG_MISMATCH:  // value 7
        // ...
}

Aber dieser Zweig stimmt niemals überein. Der Expat-Parser gibt 76 für ein nicht übereinstimmendes Tag zurück, während XML_ERROR_TAG_MISMATCH die Konstante 7 ist – es handelt sich um unterschiedliche Nummerierungsschemata, sodass der Vergleich stillschweigend fehlschlägt. Der zuverlässige Ansatz besteht darin, den Code stets mit xml_error_string() in Text umzuwandeln, anstatt rohe Zahlen zu vergleichen:

<?php
$samples = [
    'good'      => "<note><to>Ann</to></note>",
    'mismatch'  => "<note><to>Ann</from></note>",
    'truncated' => "<note><to>Ann",
];

foreach ($samples as $label => $xml) {
    $parser = xml_parser_create();
    $ok = xml_parse_into_struct($parser, $xml, $values);
    $code = xml_get_error_code($parser);
    printf("%-9s -> code %d (%s)\n", $label, $code, xml_error_string($code) ?: 'OK');
    xml_parser_free($parser);
}

Ausgabe:

good      -> code 0 (No error)
mismatch  -> code 76 (Mismatched tag)
truncated -> code 5 (Invalid document end)

Ein Code von 0 (XML_ERROR_NONE) bestätigt, dass das Dokument fehlerfrei geparst wurde – genau das liefert das wohlgeformte good-Beispiel.

Den Fehler dem Benutzer anzeigen

In einer echten Anwendung – etwa einem Handler für eine hochgeladene XML-Datei – protokollieren Sie typischerweise das technische Detail und zeigen die benutzerfreundliche Meldung an:

$parser = xml_parser_create();
$xml    = file_get_contents($_FILES['xml_file']['tmp_name']);

if (!xml_parse_into_struct($parser, $xml, $values)) {
    $code = xml_get_error_code($parser);
    $line = xml_get_current_line_number($parser);

    // For the logs / developers:
    error_log("XML parse failed on line $line: " . xml_error_string($code));

    // For the user:
    $userMessage = "We couldn't read that file — please check it is valid XML.";
}
xml_parser_free($parser);

Wann verwenden (und wann nicht)

xml_get_error_code() gehört zur Expat-basierten XML-Parser-Erweiterung – derselben Familie wie xml_parser_create() und xml_parse_into_struct(). Verwenden Sie sie, wenn Sie ereignis- bzw. streambasiertes Parsen mit dieser Erweiterung durchführen und auf einen Fehler reagieren müssen.

Wenn Sie XML stattdessen mit SimpleXML oder DOM parsen, gilt diese Funktion nicht – diese verwenden die libxml-Fehler-API. Verwenden Sie in diesem Fall libxml_get_last_error() (nach dem Aufruf von libxml_use_internal_errors(true)), um den Fehler zu untersuchen. Informationen zu diesem Arbeitsablauf finden Sie in der SimpleXML-Übersicht.

Fazit

xml_get_error_code() ruft den numerischen Expat-Fehlercode für den letzten Fehler einer XML-Parser-Instanz ab. Das bewährte Muster lautet: Prüfen Sie den Rückgabewert der Parse-Funktion; wenn er false ist, rufen Sie xml_get_error_code() auf und übergeben das Ergebnis an xml_error_string() für eine lesbare Meldung – vergleichen Sie den rohen Code nicht mit XML_ERROR_*-Konstanten, da die Expat-Nummerierung nicht damit übereinstimmt. Kombinieren Sie die Funktion mit xml_get_current_line_number(), um Benutzer (und Ihre Logs) auf die genaue Stelle zu verweisen, an der das Dokument fehlerhaft ist.

Übungen