libxml_clear_errors()

Функция libxml_clear_errors() в PHP очищает внутренний буфер ошибок, заполняемый расширениями на основе libxml — такими как DOMDocument, SimpleXML и XMLReader. На этой странице объясняется, когда libxml собирает ошибки, почему их нужно очищать, и как совмещать libxml_clear_errors() с другими функциями API ошибок libxml.

Синтаксис

libxml_clear_errors(): void

Функция не принимает аргументов и не возвращает значения (void). Она доступна начиная с PHP 5.1.0 и работает во всех современных версиях PHP.

Зачем нужно очищать ошибки libxml

По умолчанию libxml выводит ошибки разбора как предупреждения PHP. Чтобы обрабатывать их самостоятельно, вызывают libxml_use_internal_errors(true). После этого libxml перестаёт выводить предупреждения и молча добавляет каждую ошибку во внутренний буфер.

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

libxml_clear_errors() очищает этот буфер, предоставляя чистый старт перед следующей операцией.

Как использовать libxml_clear_errors()

Типичный порядок работы:

1. Включить внутреннюю обработку ошибок с помощью libxml_use_internal_errors(true).
2. Выполнить разбор или валидацию документа.
3. Прочитать собранные ошибки с помощью libxml_get_errors() (или libxml_get_last_error()).
4. Вызвать libxml_clear_errors() для сброса буфера перед обработкой следующего документа.

Ниже приведён самодостаточный, работоспособный пример, который загружает некорректный XML из строки, изучает ошибки, а затем очищает их:

<?php
// 1. Capture libxml errors in the internal buffer instead of emitting warnings.
libxml_use_internal_errors(true);

// Intentionally malformed XML: <title> is closed by </book>, not </title>.
$xml = '<book><title>PHP</book>';

$doc = new DOMDocument();
$doc->loadXML($xml);

// 2. Inspect the errors that were collected.
$errors = libxml_get_errors();
echo "Errors before clearing: " . count($errors) . "\n";
echo "First message: " . trim($errors[0]->message) . "\n";

// 3. Clear the buffer.
libxml_clear_errors();

// 4. The buffer is now empty.
echo "Errors after clearing: " . count(libxml_get_errors()) . "\n";

Вывод программы:

Errors before clearing: 2
First message: Opening and ending tag mismatch: title line 1 and book
Errors after clearing: 0

Валидация по схеме

libxml_clear_errors() наиболее полезна при обработке документов в цикле. После каждой валидации результат читается, затем буфер очищается, чтобы следующий документ начинался с чистого состояния:

<?php
libxml_use_internal_errors(true);

$documents = ['a.xml', 'b.xml', 'c.xml'];

foreach ($documents as $file) {
    $doc = new DOMDocument();
    $doc->load($file);

    if ($doc->schemaValidate('schema.xsd')) {
        echo "$file is valid\n";
    } else {
        // Only the errors for THIS document, because we clear after each one.
        foreach (libxml_get_errors() as $error) {
            echo "$file: " . trim($error->message) . "\n";
        }
    }

    // Reset the buffer before validating the next file.
    libxml_clear_errors();
}

Без вызова libxml_clear_errors() в конце каждой итерации ошибки из a.xml появились бы и при выводе ошибок для b.xml.

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

• Очистка не отключает сбор ошибок. libxml_clear_errors() лишь опустошает буфер; libxml продолжает собирать новые ошибки, пока действует libxml_use_internal_errors(true).
• Буфер является глобальным. Он разделяется между DOMDocument, SimpleXML и XMLReader. Очистка затрагивает все три расширения.
• Порядок важен. Всегда читайте ошибки с помощью libxml_get_errors() перед очисткой — после очистки они будут безвозвратно удалены.

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

• libxml_use_internal_errors() — включить или отключить внутренний буфер ошибок.
• libxml_get_errors() — получить все ошибки, находящиеся в буфере.
• libxml_get_last_error() — получить только последнюю ошибку.

Заключение

Функция libxml_clear_errors() предоставляет простой способ управления внутренним буфером ошибок libxml. Сбрасывая буфер после таких операций, как DOMDocument::load() или DOMDocument::schemaValidate(), вы предотвращаете попадание устаревших ошибок в последующие результаты — что особенно важно в циклах и долгоживущих скриптах.

Практика