xml_error_string()

La función xml_error_string() es una función integrada de PHP que recupera una descripción en texto de un error del analizador XML. Pertenece a la extensión heredada XML Parser. Al analizar archivos XML con SimpleXML u otras bibliotecas modernas, los errores se gestionan normalmente con libxml_get_errors(), ya que la extensión xml heredada está obsoleta en el PHP moderno.

La función xml_error_string() es útil cuando necesitas obtener un mensaje de error comprensible para flujos de trabajo de análisis XML heredados, aunque las aplicaciones modernas deberían preferir libxml_get_errors() para SimpleXML.

Sintaxis

La sintaxis de la función xml_error_string() es la siguiente:

sintaxis de la función xml_error_string()

xml_error_string(int $error_code): string|false

Parámetros

• $error_code — un código de error entero, tal como lo devuelve xml_get_error_code(). La extensión XML Parser expone estos códigos como constantes XML_ERROR_* (por ejemplo, XML_ERROR_NONE es 0, que significa "sin error").

Valor de retorno

xml_error_string() devuelve una cadena legible que describe el código de error dado (como "Attribute without value"). Si el código es desconocido, devuelve false. Ten en cuenta que la función solo traduce un código a texto — no indica dónde en el documento ocurrió el error; para eso también necesitas xml_get_current_line_number() y xml_get_current_column_number().

Ejemplos de uso

Veamos algunos ejemplos prácticos del uso de xml_error_string() en PHP.

Ejemplo 1: Recuperar una cadena de error del analizador XML (XML Parser heredado)

La función xml_error_string() funciona con la extensión XML Parser heredada. Puedes usarla para analizar XML y recuperar la cadena de error de la siguiente manera:

analizar el archivo XML y recuperar la cadena de error usando xml_error_string() en PHP

$parser = xml_parser_create();
$xml_data = "<invalid xml>";
xml_parse($parser, $xml_data);

$error_code = xml_get_error_code($parser);
if ($error_code !== XML_ERROR_NONE) {
  $error_string = xml_error_string($error_code);
  echo "Error: $error_string";
}

xml_parser_free($parser);

Este código crea un analizador XML con xml_parser_create(), intenta analizar la cadena mal formada "<invalid xml>" (el xml se lee como un nombre de atributo sin valor), y comprueba si hay errores. xml_get_error_code() devuelve un código distinto de cero, xml_error_string() convierte ese código en texto, y el script libera el analizador con xml_parser_free().

Resultado:

Error: Attribute without value

Ejemplo 2: Localizar dónde ocurrió el error

Una cadena de error sin contexto rara vez ayuda a un desarrollador a corregir el documento. Combina xml_error_string() con las funciones de número de línea y columna para informar exactamente dónde se detuvo el analizador:

mostrar el mensaje de error junto con su ubicación

$parser = xml_parser_create();
$xml_data = "<book>\n  <title>Hi</titlex>\n</book>";

if (!xml_parse($parser, $xml_data, true)) {
  $code = xml_get_error_code($parser);
  printf(
    "Error %d: %s at line %d, column %d\n",
    $code,
    xml_error_string($code),
    xml_get_current_line_number($parser),
    xml_get_current_column_number($parser)
  );
}

xml_parser_free($parser);

Aquí la etiqueta de cierre </titlex> no coincide con la apertura <title>, por lo que el análisis falla en la línea 2. Las funciones de ubicación informan el punto exacto:

Resultado:

Error 76: Mismatched tag at line 2, column 21

El código numérico exacto y el texto dependen de tu versión de libxml, pero xml_error_string() siempre devuelve el mensaje legible correspondiente al código que reporta xml_get_error_code().

Ejemplo 2: Gestionar errores de SimpleXML (enfoque moderno recomendado)

Si usas la biblioteca SimpleXML, xml_error_string() no es aplicable. En su lugar, usa libxml_use_internal_errors(true) y libxml_get_errors() para gestionar los fallos de análisis:

Mostrar un mensaje de error del analizador XML

libxml_use_internal_errors(true);

if (isset($_FILES["xml_file"])) {
  $xml = simplexml_load_file($_FILES["xml_file"]["tmp_name"]);
  if ($xml === false) {
    $errors = libxml_get_errors();
    foreach ($errors as $error) {
      echo "Error: " . $error->message;
    }
  } else {
    // process the XML file
  }
}

Este código habilita el manejo interno de errores para SimpleXML, comprueba si se subió un archivo XML mediante el array $_FILES e intenta cargar el archivo. Si ocurre un error durante el análisis, recupera los detalles del error con libxml_get_errors() y muestra el mensaje de error al usuario. Si no se producen errores, el código puede procesar el archivo XML según sea necesario.

Códigos de error comunes del analizador XML

La extensión XML Parser define constantes con nombre para los casos de "sin error" y de documento bien formado. El único valor en el que siempre puedes confiar es XML_ERROR_NONE (0), que significa que el análisis se realizó correctamente. Algunos códigos bajos comunes y las cadenas que xml_error_string() devuelve para ellos son:

Atención: el entero exacto que devuelve un análisis real, y su texto, son producidos por la biblioteca libxml subyacente y varían entre versiones de PHP/libxml — por eso siempre pasa el valor en vivo de xml_get_error_code() a xml_error_string() en lugar de asumir un número fijo. Solo la comprobación de "éxito" con XML_ERROR_NONE (0) es estable entre versiones.

Comparar contra XML_ERROR_NONE (en lugar de un 0 codificado de forma fija) mantiene clara la intención de tu comprobación de éxito.

Funciones relacionadas

• xml_get_error_code() — devuelve el código numérico que se pasa a xml_error_string().
• xml_parse() — ejecuta el analizador y genera el error que luego describes.
• xml_get_current_line_number() / xml_get_current_column_number() — localiza el error en el código fuente.
• libxml_get_errors() — el equivalente moderno utilizado con SimpleXML.

Conclusión

En este artículo, hemos analizado la función xml_error_string() de PHP y cómo puede usarse para recuperar una descripción en texto de un error del analizador XML en flujos de trabajo de análisis XML heredados. Hemos explicado qué hace la función, su sintaxis y hemos proporcionado ejemplos de cómo puede utilizarse. Para las aplicaciones PHP modernas que usan SimpleXML, recomendamos usar libxml_use_internal_errors(true) y libxml_get_errors() para gestionar los fallos de análisis, asegurando que tus aplicaciones web sean más robustas y fáciles de usar.

Práctica