libxml_set_streams_context()

A função libxml_set_streams_context() define o contexto de stream que o libxml usará na próxima vez que carregar ou gravar um documento por um protocolo de rede como HTTP, HTTPS ou FTP. É o mecanismo que permite anexar cabeçalhos de requisição personalizados, credenciais de autenticação, timeouts ou um proxy à requisição de rede implícita que funções como DOMDocument::load() e simplexml_load_file() realizam nos bastidores.

Esta página explica a assinatura, quando você realmente precisa dela, um exemplo completo e funcional, e os erros mais comuns.

Sintaxe

libxml_set_streams_context(resource $context): void

O contexto é aplicado globalmente ao libxml para a requisição atual e permanece em vigor até que você defina um diferente ou o script termine.

Quando eu usaria isso?

A maioria das cargas do libxml lê um arquivo local ou uma string já obtida, portanto você nunca precisa desta função. Você a utiliza apenas quando o próprio libxml abre a conexão de rede — ou seja, quando você passa uma URL http://, https:// ou ftp:// para um carregador. Casos típicos:

• O servidor remoto requer um cabeçalho Authorization (autenticação Basic, um token bearer).
• Você precisa de um User-Agent personalizado, cookie ou outro cabeçalho de requisição.
• Você deve definir um timeout para que um host lento não trave seu script.
• A requisição precisa passar por um proxy HTTP.

Se você buscar o XML por conta própria (por exemplo, com cURL ou file_get_contents()) e depois analisar a string resultante com simplexml_load_string() ou DOMDocument::loadXML(), o libxml nunca acessa a rede e esta função não tem utilidade.

Como usar

Crie o contexto com stream_context_create(), registre-o e depois carregue seu documento:

<?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;
?>

Como o libxml suprime erros em nível de protocolo, combine isso com libxml_use_internal_errors() para inspecionar falhas em vez de receber avisos silenciosos:

<?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();
}
?>

Consulte libxml_get_errors() para saber como ler os erros coletados.

Erros comuns

• Afeta apenas cargas de rede. Chamá-la antes de analisar um arquivo local ou uma string em memória não tem efeito.
• Múltiplos cabeçalhos devem ser separados por \r\n. A opção header é uma única string; junte as linhas com "\r\n" (ou passe um array de strings).
• A ordem importa. Chame libxml_set_streams_context() antes da chamada load() / simplexml_load_file(), não depois.
• Sem suporte a https://? O wrapper de stream HTTPS requer que a extensão OpenSSL esteja habilitada. Sem ela, o libxml não consegue abrir URLs https:// de forma alguma.
• O carregamento remoto deve ser permitido. Algumas configurações de segurança do libxml (e a diretiva ini allow_url_fopen) podem bloquear completamente o carregamento de documentos remotos.

Funções relacionadas

• libxml_use_internal_errors() — capturar erros do parser em vez de emitir avisos.
• libxml_get_errors() — recuperar os erros capturados.
• simplexml_load_file() — um carregador SimpleXML que também respeita o contexto de stream.
• Visão geral do libxml no PHP — a extensão libxml de forma mais ampla.

Conclusão

libxml_set_streams_context() é a ponte entre os contextos de stream do PHP e os carregadores de rede do libxml. Sempre que você carregar XML diretamente de uma URL e precisar de autenticação, cabeçalhos personalizados, timeout ou proxy, crie um contexto com stream_context_create() e registre-o com esta função antes do carregamento. Para arquivos locais ou strings pré-obtidas, você não precisa dela.

Prática