xml_get_error_code()

La función xml_get_error_code() es una función integrada de PHP que recupera el código de error de un analizador XML. Cuando analizas XML con la extensión XML Parser (Expat) de PHP, las funciones de análisis devuelven false en el momento en que algo sale mal, pero false solo no te dice qué salió mal. xml_get_error_code() devuelve un código numérico que describe el error más reciente, el cual puedes traducir a un mensaje legible con xml_error_string().

Esta página cubre la sintaxis de la función, qué devuelve, cómo convertir el código en un mensaje, y el error común que confunde a la mayoría: el código devuelto es un código de error Expat, no la constante XML_OPTION_* que podrías esperar.

Sintaxis

xml_get_error_code(XMLParser $parser): int

$parser es el analizador creado por xml_parser_create() (o xml_parser_create_ns()). En PHP 8.0+ es un objeto XMLParser; en PHP 7.x y versiones anteriores era un resource. El código de este capítulo funciona en ambos.

Valor de retorno

La función devuelve un código de error de tipo integer:

• 0 (la constante XML_ERROR_NONE) significa sin error — el análisis fue exitoso.
• Cualquier valor distinto de cero identifica el tipo de fallo. Pásalo a xml_error_string() para obtener una descripción legible, y a xml_get_current_line_number() para encontrar dónde ocurrió.

Comprueba siempre primero el valor de retorno de la función de análisis (xml_parse() / xml_parse_into_struct()); llama a xml_get_error_code() solo después de que devuelva false.

Un ejemplo completo y ejecutable

El siguiente ejemplo analiza una cadena XML deliberadamente mal formada (la etiqueta de cierre no coincide con la de apertura), luego reporta el código de error, su mensaje y el número de línea. Como el XML está incluido como cadena, puedes copiarlo y ejecutarlo tal cual — no se necesita ningún archivo.

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

Salida:

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

xml_parse_into_struct() devuelve false, por lo que llamamos a xml_get_error_code() y pasamos el resultado directamente a xml_error_string() para obtener el mensaje "Mismatched tag".

El error común: el código es un código Expat

Es tentador comparar el resultado con constantes como XML_ERROR_TAG_MISMATCH en un switch:

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

Pero esta rama nunca coincide. El analizador Expat devuelve 76 para una etiqueta mal emparejada, mientras que XML_ERROR_TAG_MISMATCH es la constante 7 — son esquemas de numeración distintos, por lo que la comparación falla silenciosamente. El enfoque fiable es siempre convertir el código a texto con xml_error_string() en lugar de comparar números directamente:

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

Salida:

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

Un código de 0 (XML_ERROR_NONE) confirma que el documento se analizó correctamente, que es exactamente lo que produce la muestra bien formada good.

Mostrar el error al usuario

En una aplicación real — por ejemplo, un manejador para un archivo XML subido — normalmente registras el detalle técnico y muestras el mensaje amigable:

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

Cuándo usarla (y cuándo no)

xml_get_error_code() pertenece a la extensión XML Parser basada en Expat — la misma familia que xml_parser_create() y xml_parse_into_struct(). Úsala cuando estés haciendo análisis basado en eventos/flujo con esa extensión y necesites reaccionar ante un fallo.

Si analizas XML con SimpleXML o DOM en su lugar, esta función no aplica — esas extensiones usan la API de errores de libxml. En ese caso usa libxml_get_last_error() (después de llamar a libxml_use_internal_errors(true)) para inspeccionar qué salió mal. Consulta la descripción general de SimpleXML para ese flujo de trabajo.

Conclusión

xml_get_error_code() recupera el código de error numérico de Expat para el último fallo en una instancia de XML Parser. El patrón confiable es: comprueba el valor de retorno de la función de análisis, y si es false, llama a xml_get_error_code() y pasa el resultado a xml_error_string() para obtener un mensaje legible — no compares el código directamente con las constantes XML_ERROR_*, ya que la numeración de Expat no se corresponde con ellas. Combínala con xml_get_current_line_number() para señalar a los usuarios (y a tus registros) el punto exacto donde el documento falló.

Práctica