xml_error_string()

Функция xml_error_string() — это встроенная функция PHP, которая возвращает строковое описание ошибки XML-парсера. Она относится к устаревшему расширению XML Parser. При разборе XML-файлов с помощью SimpleXML или других современных библиотек ошибки, как правило, обрабатываются через libxml_get_errors(), поскольку устаревшее расширение xml объявлено устаревшим в современных версиях PHP.

Функция xml_error_string() полезна, когда необходимо получить понятное пользователю сообщение об ошибке в рамках устаревших рабочих процессов разбора XML, хотя современные приложения должны отдавать предпочтение libxml_get_errors() при работе с SimpleXML.

Синтаксис

Синтаксис функции xml_error_string() выглядит следующим образом:

синтаксис функции xml_error_string()

xml_error_string(int $error_code): string|false

Параметры

• $error_code — целочисленный код ошибки, возвращаемый функцией xml_get_error_code(). Расширение XML Parser предоставляет эти коды в виде констант XML_ERROR_* (например, XML_ERROR_NONE равно 0, что означает «нет ошибки»).

Возвращаемое значение

xml_error_string() возвращает удобочитаемую строку с описанием заданного кода ошибки (например, "Attribute without value"). Если код неизвестен, функция возвращает false. Следует учесть, что функция лишь преобразует код в текст — она не сообщает, где именно в документе произошла ошибка; для этого также потребуются xml_get_current_line_number() и xml_get_current_column_number().

Примеры использования

Рассмотрим несколько практических примеров применения xml_error_string() в PHP.

Пример 1: Получение строки ошибки XML-парсера (устаревший XML Parser)

Функция xml_error_string() работает с устаревшим расширением XML Parser. С её помощью можно разобрать XML и получить строку ошибки:

разбор XML-файла и получение строки ошибки с помощью xml_error_string() в 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);

Этот код создаёт XML-парсер с помощью xml_parser_create(), пытается разобрать некорректную строку "<invalid xml>" (слово xml воспринимается как имя атрибута без значения) и проверяет наличие ошибок. xml_get_error_code() возвращает ненулевой код, xml_error_string() преобразует этот код в текст, а скрипт освобождает парсер с помощью xml_parser_free().

Вывод:

Error: Attribute without value

Пример 2: Определение места возникновения ошибки

Одной строки ошибки разработчику обычно недостаточно для исправления документа. Объедините xml_error_string() с функциями получения номера строки и столбца, чтобы точно указать место, где парсер остановился:

вывод сообщения об ошибке вместе с её местоположением

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

Здесь закрывающий тег </titlex> не совпадает с открывающим <title>, поэтому разбор завершается с ошибкой на строке 2. Функции определения местоположения сообщают точное место:

Вывод:

Error 76: Mismatched tag at line 2, column 21

Точный числовой код и формулировка зависят от версии libxml, однако xml_error_string() всегда возвращает соответствующее удобочитаемое сообщение для любого кода, который возвращает xml_get_error_code().

Пример 2: Обработка ошибок SimpleXML (рекомендуемый современный подход)

При использовании библиотеки SimpleXML функция xml_error_string() неприменима. Вместо этого следует использовать libxml_use_internal_errors(true) и libxml_get_errors() для обработки ошибок разбора:

Отображение сообщения об ошибке 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
  }
}

Этот код включает внутреннюю обработку ошибок для SimpleXML, проверяет, был ли загружен XML-файл через массив $_FILES, и пытается загрузить файл. Если при разборе возникает ошибка, код получает подробную информацию с помощью libxml_get_errors() и выводит сообщение об ошибке пользователю. Если ошибок нет, код может обрабатывать XML-файл по мере необходимости.

Распространённые коды ошибок XML-парсера

Расширение XML Parser определяет именованные константы для случаев отсутствия ошибок и нарушения правильности формата. Единственное значение, на которое всегда можно полагаться, — это XML_ERROR_NONE (0), означающее успешный разбор. Несколько распространённых кодов и строки, которые возвращает для них xml_error_string():

Обратите внимание: точное целое число, возвращаемое при реальном разборе, и его формулировка определяются базовой библиотекой libxml и могут различаться в зависимости от версии PHP/libxml — поэтому всегда передавайте живое значение от xml_get_error_code() в xml_error_string(), не предполагая фиксированного числа. Стабильной между версиями остаётся только проверка «успеха» через XML_ERROR_NONE (0).

Сравнение с XML_ERROR_NONE (а не с жёстко заданным 0) делает намерение проверки успеха более понятным.

Связанные функции

• xml_get_error_code() — возвращает числовой код, который передаётся в xml_error_string().
• xml_parse() — запускает парсер и вызывает ошибку, которую затем описывает xml_error_string().
• xml_get_current_line_number() / xml_get_current_column_number() — определяют местоположение ошибки в источнике.
• libxml_get_errors() — современный аналог, используемый с SimpleXML.

Заключение

В этой статье мы рассмотрели функцию PHP xml_error_string() и то, как она может использоваться для получения строкового описания ошибки XML-парсера в рамках устаревших рабочих процессов разбора XML. Мы объяснили, что делает функция, её синтаксис и привели примеры её применения. Для современных PHP-приложений, использующих SimpleXML, рекомендуется применять libxml_use_internal_errors(true) и libxml_get_errors() для обработки ошибок разбора, что делает веб-приложения более надёжными и удобными для пользователей.

Практика