xml_get_error_code()

The xml_get_error_code() function is a PHP built-in function that retrieves the error code of an XML parser. When you parse XML with PHP's XML Parser (Expat) extension, the parse functions return false the moment something goes wrong — but false alone doesn't tell you what went wrong. xml_get_error_code() returns a numeric code describing the most recent error, which you can then translate into a human-readable message with xml_error_string().

This page covers the function's syntax, what it returns, how to turn the code into a message, and the gotcha that trips most people up: the returned code is an Expat error code, not the XML_OPTION_* constant you might expect.

Syntax

xml_get_error_code(XMLParser $parser): int

$parser is the parser created by xml_parser_create() (or xml_parser_create_ns()). In PHP 8.0+ this is an XMLParser object; in PHP 7.x and earlier it was a resource. The code in this chapter works on both.

Return value

The function returns an integer error code:

• 0 (the constant XML_ERROR_NONE) means no error — the parse succeeded.
• Any non-zero value identifies the kind of failure. Pass it to xml_error_string() to get a readable description, and to xml_get_current_line_number() to find where it happened.

Always check the return value of the parse function first (xml_parse() / xml_parse_into_struct()); only call xml_get_error_code() after it returns false.

A complete, runnable example

The example below parses a deliberately broken XML string (the closing tag doesn't match the opening one), then reports the error code, its message, and the line number. Because the XML is embedded as a string, you can copy and run it as-is — no file needed.

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

Output:

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

xml_parse_into_struct() returns false, so we call xml_get_error_code() and feed the result straight into xml_error_string() to get the message "Mismatched tag".

The gotcha: the code is an Expat code

It's tempting to compare the result against constants like XML_ERROR_TAG_MISMATCH in a switch:

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

But this branch never matches. The Expat parser returns 76 for a mismatched tag, while XML_ERROR_TAG_MISMATCH is the constant 7 — they are different numbering schemes, so the comparison silently fails. The reliable approach is to always convert the code to text with xml_error_string() rather than matching raw numbers:

<?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);
}

Output:

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

A code of 0 (XML_ERROR_NONE) confirms the document parsed cleanly, which is exactly what the well-formed good sample produces.

Surfacing the error to a user

In a real application — say, a handler for an uploaded XML file — you typically log the technical detail and show the friendly message:

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

When to use it (and when not to)

xml_get_error_code() belongs to the Expat-based XML Parser extension — the same family as xml_parser_create() and xml_parse_into_struct(). Reach for it when you are doing event/stream-based parsing with that extension and need to react to a failure.

If you parse XML with SimpleXML or DOM instead, this function does not apply — those use the libxml error API. In that case use libxml_get_last_error() (after calling libxml_use_internal_errors(true)) to inspect what went wrong. See the SimpleXML overview for that workflow.

Conclusion

xml_get_error_code() retrieves the numeric Expat error code for the last failure on an XML Parser instance. The dependable pattern is: check the parse function's return value, and if it is false, call xml_get_error_code() and pass the result to xml_error_string() for a readable message — don't compare the raw code against XML_ERROR_* constants, since the Expat numbering doesn't line up with them. Pair it with xml_get_current_line_number() to point users (and your logs) at the exact spot the document broke.

Practice