PHP: полный мануал с примерами, функциями и ООП

<?php
declare(strict_types=1);

$previous = libxml_use_internal_errors(true);
try {
    $document = new DOMDocument();
    if (!$document->loadXML('<order>42')) {
        echo "Заказ не принят: повреждённый XML\n";
    }
} finally {
    libxml_clear_errors();
    libxml_use_internal_errors($previous);
}

Заказ не принят: повреждённый XML

true направляет сообщения libxml во внутренний список. Возврат setter — старый режим, который сохраняем в $previous; успех разбора проверяем отдельно по loadXML. В документе отсутствует закрывающий /order. finally очищает нашу диагностику и возвращает прежний режим, даже если дальнейший код выбросит исключение.

<?php
declare(strict_types=1);

$previous = libxml_use_internal_errors(true);
libxml_clear_errors();
try {
    $document = new DOMDocument();
    if (!$document->load(__DIR__ . '/invoice.xml')) {
        $errors = libxml_get_errors();
        echo 'invoice.xml, строка ', $errors[0]->line, ": накладная не принята\n";
    }
} finally {
    libxml_clear_errors();
    libxml_use_internal_errors($previous);
}

invoice.xml, строка 2: накладная не принята

Файл открывает invoice, затем order и ошибочно закрывает invoice в строке 2, пока order ещё открыт. Это уже полезная адресация проблемы, без вывода серверного пути и всего документа. Наличие internal_errors не исправляет XML и не перехватывает любые ошибки PHP.

<?php
declare(strict_types=1);

$previous = libxml_use_internal_errors(true);
libxml_clear_errors();
try {
    $document = new DOMDocument();
    if ($document->loadXML('<order>42</order>')) {
        echo 'Заказ ', $document->documentElement->textContent, ": XML прочитан\n";
    }
    if (libxml_get_errors() === []) { echo "Замечаний парсера нет\n"; }
} finally { libxml_clear_errors(); libxml_use_internal_errors($previous); }

Заказ 42: XML прочитан
Замечаний парсера нет

libxml_get_errors не принимает аргументов и возвращает массив сообщений. Пустой массив означает только отсутствие накопленных сообщений: сам факт разбора подтверждён loadXML. Без вызова парсера такой же пустой массив не доказывал бы корректность файла.

<?php
declare(strict_types=1);

$previous = libxml_use_internal_errors(true);
libxml_clear_errors();
try {
    $document = new DOMDocument();
    $document->loadXML("<invoice>\n<order>42</invoice>");
    $errors = libxml_get_errors();
    libxml_clear_errors();
    echo 'Отчёт импорта 17: первая проблема в строке ', $errors[0]->line, "\n";
    echo libxml_get_errors() === [] ? "Очередь для следующей попытки пуста\n" : "Остались сообщения\n";
} finally { libxml_clear_errors(); libxml_use_internal_errors($previous); }

Отчёт импорта 17: первая проблема в строке 2
Очередь для следующей попытки пуста

get_errors возвращает PHP-массив объектов LibXMLError. clear_errors очищает очередь движка, но уже полученный $errors остаётся доступен для отчёта. Чтение get_errors само по себе очередь не очищает. После отправки отчёта не накапливайте бесконечно и собственные копии.

<?php
declare(strict_types=1);

libxml_clear_errors();
$lastError = libxml_get_last_error();
if ($lastError === false) {
    echo "Новая попытка: сообщений XML пока нет\n";
}

Новая попытка: сообщений XML пока нет

false здесь означает отсутствие последнего сообщения. Разбора ещё не было: зелёную отметку «файл проверен» показывать рано. Сначала проверяем результат парсера, затем при необходимости читаем объект ошибки.

<?php
declare(strict_types=1);

$previous = libxml_use_internal_errors(true);
libxml_clear_errors();
try {
    $document = new DOMDocument();
    if (!$document->loadXML("<order>\n42")) {
        $error = libxml_get_last_error();
        echo "Импорт заказа отклонён\n";
        if ($error !== false) { echo 'Последняя диагностика: строка ', $error->line, "\n"; }
    }
} finally { libxml_clear_errors(); libxml_use_internal_errors($previous); }

Импорт заказа отклонён
Последняя диагностика: строка 2

Сначала проверка !== false, только затем ->line: функция может не вернуть объект. Последнее сообщение не обязательно первопричина. Полную последовательность сообщения разбирайте через get_errors; точные английские формулировки зависят от libxml.

<?php
declare(strict_types=1);

$previous = libxml_use_internal_errors(true);
try {
    foreach (['<order>', "<invoice>\n<order>"] as $text) {
        libxml_clear_errors();
        $document = new DOMDocument();
        $document->loadXML($text);
        $error = libxml_get_last_error();
        if ($error !== false) { echo 'Отказ текущего документа: строка ', $error->line, "\n"; }
    }
} finally { libxml_clear_errors(); libxml_use_internal_errors($previous); }

Отказ текущего документа: строка 1
Отказ текущего документа: строка 2

После первой очистки режим накопления остаётся включённым: следующий документ снова даёт собственную диагностику. clear_errors возвращает void, не исправляет ни первый, ни второй XML. Следующий пример добавляет успешную попытку после отказа.

<?php
declare(strict_types=1);

$previous = libxml_use_internal_errors(true);
try {
    foreach (['<order>', '<order>42</order>'] as $text) {
        libxml_clear_errors();
        $document = new DOMDocument();
        $ok = $document->loadXML($text);
        echo $ok ? "accepted\n" : "rejected\n";
        echo count(libxml_get_errors()) > 0 ? "has diagnostics\n" : "clean\n";
    }
} finally { libxml_clear_errors(); libxml_use_internal_errors($previous); }

rejected
has diagnostics
accepted
clean

Здесь accepted означает только синтаксически разобранный XML. Наличие нужных полей, допустимый номер заказа и доверие к отправителю проверяются отдельно. Очистка границ особенно важна в импортах тысяч документов.

<?php
declare(strict_types=1);

$original = libxml_get_external_entity_loader();
$resolveLocal = static function (?string $public, ?string $system, array $context) {
    return $system === 'urn:shop:label' ? __DIR__ . '/label.txt' : null;
};
try {
    libxml_set_external_entity_loader($resolveLocal);
    $saved = libxml_get_external_entity_loader();
    libxml_set_external_entity_loader(static fn() => null);
    libxml_set_external_entity_loader($saved);
    $document = new DOMDocument();
    $document->loadXML('<!DOCTYPE product [<!ENTITY label SYSTEM "urn:shop:label">]><product>&label;</product>', LIBXML_NOENT);
    echo 'Восстановленный загрузчик: ', $document->textContent, "\n";
} finally { libxml_set_external_entity_loader($original); }

Восстановленный загрузчик: Desk

Getter без аргументов сохраняет сам callback, чтобы временная политика не сломала другие XML-операции. После восстановления реальная подстановка читает только известный label.txt. Возврат строки из callback — путь к содержимому, не само содержимое. NOENT включён исключительно в этом контролируемом опыте с заданной зависимостью.

<?php
declare(strict_types=1);

$previous = libxml_get_external_entity_loader();
try {
    libxml_set_external_entity_loader(null);
    var_dump(libxml_get_external_entity_loader());
    libxml_set_external_entity_loader(static fn() => null);
    var_dump(is_callable(libxml_get_external_entity_loader()));
} finally { libxml_set_external_entity_loader($previous); }

NULL
bool(true)

Не вызывайте полученный callback ради проверки: это может открыть ресурс или изменить его состояние. Сохраните и восстановите его как значение.

<?php
declare(strict_types=1);

$loader = libxml_get_external_entity_loader();
$errors = libxml_use_internal_errors(true);
libxml_clear_errors();
$denied = [];
try {
    libxml_set_external_entity_loader(static function (?string $public, ?string $system, array $context) use (&$denied) {
        $denied[] = $system;
        return null;
    });
    $document = new DOMDocument();
    $document->loadXML('<!DOCTYPE product [<!ENTITY label SYSTEM "urn:shop:unknown">]><product>&label;</product>', LIBXML_NOENT);
    if ($denied !== []) {
        echo 'Импорт отменён: не разрешена зависимость ', $denied[0], "\n";
    }
} finally {
    libxml_set_external_entity_loader($loader);
    libxml_clear_errors(); libxml_use_internal_errors($errors);
}

Импорт отменён: не разрешена зависимость urn:shop:unknown

return null от callback отказывает в разрешении запрошенной сущности; libxml_set_external_entity_loader(null), напротив, возвращает штатный загрузчик. loadXML может построить дерево с пустым содержимым, поэтому отказ зависимости здесь отдельно запрещает импорт. Идентификатор urn не является адресом сети; чтения внешнего ресурса нет.

<?php
declare(strict_types=1);

$loader = libxml_get_external_entity_loader();
$errors = libxml_use_internal_errors(true);
libxml_clear_errors();
try {
    libxml_set_external_entity_loader(static function (?string $public, ?string $system, array $context) {
        return $system === 'urn:shop:order.dtd' ? __DIR__ . '/order.dtd' : null;
    });
    foreach (['<order number="42"><item>Desk</item></order>', '<order number="43"><comment>Desk</comment></order>'] as $xml) {
        libxml_clear_errors();
        $document = new DOMDocument();
        $document->loadXML('<!DOCTYPE order SYSTEM "urn:shop:order.dtd">' . $xml, LIBXML_DTDLOAD);
        $number = $document->documentElement->getAttribute('number');
        echo 'Заказ ', $number, $document->validate() ? ": формат принят\n" : ": нарушена DTD\n";
    }
} finally {
    libxml_set_external_entity_loader($loader);
    libxml_clear_errors(); libxml_use_internal_errors($errors);
}

Заказ 42: формат принят
Заказ 43: нарушена DTD

DTD — описание допустимой структуры: order должен содержать хотя бы один item, number обязателен. XML с comment синтаксически разбирается, но не проходит правила формата. Callback связывает один известный urn с собственным order.dtd. Внешние адреса не открываются; разрешение на исходный XML и на зависимость — разные решения.

<?php
declare(strict_types=1);

$deprecated = 0;
set_error_handler(static function (int $level) use (&$deprecated): bool {
    if ($level !== E_DEPRECATED) { return false; }
    $deprecated++; return true;
});
try {
    $previous = libxml_disable_entity_loader(true);
    libxml_disable_entity_loader($previous);
} finally { restore_error_handler(); }
echo $deprecated, "\n";

2

Оба вызова наPHP8.5.11 помечены устаревшими. Перехват сделан только для наглядного опыта; рабочая миграция убирает причину deprecated, а не скрывает все сообщения.

<?php
declare(strict_types=1);

$options = LIBXML_NONET;
if (defined('LIBXML_NO_XXE')) { $options |= constant('LIBXML_NO_XXE'); }
$document = new DOMDocument();
if (!$document->loadXML('<order number="42"><item>Desk</item></order>', $options)) {
    throw new RuntimeException('Заказ не разобран');
}
echo 'Заказ ', $document->documentElement->getAttribute('number'), ': ', $document->textContent, "\n";

Заказ 42: Desk

Здесь нет DTD, подстановки внешних сущностей и вызова deprecated setter. | объединяет доступные флаги. LIBXML_NO_XXE требует PHP8.4 и libxml2.13+, поэтому проверяем defined; один LIBXML_NONET не закрывает чтение локальных файлов и не задаёт всю политику доступа.

<?php
declare(strict_types=1);

require __DIR__ . '/xml-lab.php';
[$server, $base] = startXmlLab();
try {
    $context = stream_context_create(['http' => [
        'header' => "X-Warehouse: north\r\n", 'timeout' => 2.0,
    ]]);
    libxml_set_streams_context($context);
    $document = new DOMDocument();
    if (!$document->load($base . '/stock.xml')) { throw new RuntimeException('Нет складского XML'); }
    echo 'Склад ответа: ', $document->documentElement->getAttribute('warehouse'), "\n";
    echo 'A1 — остаток ', $document->textContent, "\n";
} finally { stopXmlLab($server); }

Склад ответа: north
A1 — остаток 3

Это настоящий запрос к локальному PHP HTTP-серверу: он читает X-Warehouse и выбирает XML склада north. Без этого заголовка возвращаются default и 0. В архиве даны сервер и полностью локальный helper запуска/остановки; они нужны только лаборатории. Проверено прохождение заголовка, а не наступление тайм-аута. Setter передаёт ресурс контекста и возвращает void; load выполняет запрос отдельно.

<?php
declare(strict_types=1);

$stream = fopen('php://temp', 'w+');
if ($stream === false) { throw new RuntimeException('No stream'); }
try {
    try { libxml_set_streams_context($stream); echo "stream accepted\n"; }
    catch (TypeError $error) { echo "context required\n"; }
} finally { fclose($stream); }

context required

Проверенный PHP8.5.11 отклоняет обычный файловый поток: нужен именно ресурс контекста. Передавайте результат stream_context_create. То, что оба значения имеют тип resource, ещё не означает взаимозаменяемость их назначения.