libxml_set_streams_context()

Функция libxml_set_streams_context() устанавливает контекст потока, который libxml будет использовать при следующей загрузке или записи документа через сетевой протокол, такой как HTTP, HTTPS или FTP. Это механизм, позволяющий передавать пользовательские заголовки запросов, учётные данные, таймауты или прокси к неявным сетевым запросам, которые функции вроде DOMDocument::load() и simplexml_load_file() выполняют в фоновом режиме.

На этой странице описаны сигнатура функции, ситуации, когда она действительно нужна, полный рабочий пример и наиболее распространённые подводные камни.

Синтаксис

libxml_set_streams_context(resource $context): void

Контекст применяется глобально к libxml для текущего запроса и остаётся активным до тех пор, пока вы не установите другой или скрипт не завершится.

Когда стоит использовать?

Большинство загрузок libxml читают локальный файл или уже полученную строку, поэтому эта функция обычно не нужна. Она необходима только тогда, когда libxml сам открывает сетевое соединение — то есть когда загрузчику передаётся URL вида http://, https:// или ftp://. Типичные случаи:

• Удалённый сервер требует заголовок Authorization (Basic auth, bearer-токен).
• Нужен пользовательский User-Agent, cookie или другой заголовок запроса.
• Необходимо установить таймаут, чтобы медленный хост не подвесил скрипт.
• Запрос должен проходить через HTTP-прокси.

Если вы получаете XML самостоятельно (например, через cURL или file_get_contents()), а затем разбираете строку с помощью simplexml_load_string() или DOMDocument::loadXML(), libxml не обращается к сети и эта функция не даёт никакого эффекта.

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

Создайте контекст с помощью stream_context_create(), зарегистрируйте его, затем загрузите документ:

<?php
// 1. Describe the network request.
$context = stream_context_create([
    'http' => [
        'method'  => 'GET',
        'header'  => "Authorization: Basic " . base64_encode('username:password') . "\r\n"
                   . "User-Agent: w3docs-example\r\n",
        'timeout' => 5, // seconds
    ],
]);

// 2. Tell libxml to use it for the next network load.
libxml_set_streams_context($context);

// 3. Load a remote XML file. libxml opens the connection with the headers above.
$doc = new DOMDocument();
$doc->load('https://example.com/feed.xml');

echo $doc->documentElement->nodeName;
?>

Поскольку libxml скрывает ошибки на уровне протокола, используйте вместе с ней libxml_use_internal_errors(), чтобы перехватывать сбои вместо получения молчаливых предупреждений:

<?php
libxml_use_internal_errors(true);

$context = stream_context_create([
    'http' => ['timeout' => 5],
]);
libxml_set_streams_context($context);

$doc = new DOMDocument();
if (!$doc->load('https://example.com/feed.xml')) {
    foreach (libxml_get_errors() as $error) {
        echo trim($error->message), "\n";
    }
    libxml_clear_errors();
}
?>

Подробнее о чтении собранных ошибок см. libxml_get_errors().

Распространённые подводные камни

• Влияет только на сетевые загрузки. Вызов функции перед разбором локального файла или строки в памяти не даёт никакого эффекта.
• Несколько заголовков должны быть разделены \r\n. Параметр header — это одна строка; объединяйте строки через "\r\n" (или передайте массив строк).
• Порядок важен. Вызывайте libxml_set_streams_context() до вызова load() / simplexml_load_file(), а не после.
• Нет поддержки https://? Обёртка потока HTTPS требует включённого расширения OpenSSL. Без него libxml вообще не может открывать URL вида https://.
• Удалённая загрузка должна быть разрешена. Некоторые настройки безопасности libxml (и директива ini allow_url_fopen) могут полностью блокировать загрузку удалённых документов.

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

• libxml_use_internal_errors() — перехватывать ошибки парсера вместо вывода предупреждений.
• libxml_get_errors() — получить перехваченные ошибки.
• simplexml_load_file() — загрузчик SimpleXML, также учитывающий контекст потока.
• Обзор PHP libxml — расширение libxml в целом.

Заключение

libxml_set_streams_context() — это мост между контекстами потоков PHP и сетевыми загрузчиками libxml. Когда вы загружаете XML непосредственно по URL и вам нужны аутентификация, пользовательские заголовки, таймаут или прокси, создайте контекст с помощью stream_context_create() и зарегистрируйте его с помощью этой функции перед загрузкой. Для локальных файлов или предварительно полученных строк она вам не понадобится.

Practice