libxml_set_streams_context()

La función libxml_set_streams_context() establece el contexto de flujo que libxml utilizará la próxima vez que cargue o escriba un documento a través de un protocolo de red como HTTP, HTTPS o FTP. Es el mecanismo que permite adjuntar encabezados de solicitud personalizados, credenciales de autenticación, tiempos de espera o un proxy a la solicitud de red implícita que realizan funciones como DOMDocument::load() y simplexml_load_file() en segundo plano.

Esta página explica la firma, cuándo realmente se necesita, un ejemplo funcional completo y los errores más comunes.

Sintaxis

libxml_set_streams_context(resource $context): void

El contexto se aplica globalmente a libxml para la solicitud actual y permanece vigente hasta que se establezca uno diferente o el script termine.

¿Cuándo usarla?

La mayoría de las cargas con libxml leen un archivo local o una cadena ya obtenida, por lo que nunca se necesita esta función. Se recurre a ella solo cuando libxml mismo abre la conexión de red, es decir, cuando se pasa una URL http://, https:// o ftp:// a un cargador. Casos típicos:

• El servidor remoto requiere un encabezado Authorization (autenticación básica, un token Bearer).
• Se necesita un User-Agent personalizado, cookie u otro encabezado de solicitud.
• Se debe establecer un tiempo de espera para que un servidor lento no bloquee el script.
• La solicitud debe pasar por un proxy HTTP.

Si se obtiene el XML de forma independiente (por ejemplo con cURL o file_get_contents()) y luego se analiza la cadena resultante con simplexml_load_string() o DOMDocument::loadXML(), libxml nunca accede a la red y esta función no tiene ningún efecto útil.

Cómo usarla

Crea el contexto con stream_context_create(), regístralo y luego carga el 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;
?>

Dado que libxml silencia los errores a nivel de protocolo, combina esto con libxml_use_internal_errors() para poder inspeccionar los fallos en lugar de recibir advertencias silenciosas:

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

Consulta libxml_get_errors() para saber cómo leer los errores recopilados.

Errores comunes

• Solo afecta a cargas de red. Llamarla antes de analizar un archivo local o una cadena en memoria no tiene ningún efecto.
• Los encabezados múltiples deben separarse con \r\n. La opción header es una cadena simple; une las líneas con "\r\n" (o pasa un array de cadenas).
• El orden importa. Llama a libxml_set_streams_context() antes de la llamada a load() / simplexml_load_file(), no después.
• ¿Sin soporte para https://? El wrapper de flujo HTTPS requiere que la extensión OpenSSL esté habilitada. Sin ella, libxml no puede abrir URLs https:// en absoluto.
• La carga remota debe estar permitida. Algunas configuraciones de seguridad de libxml (y la directiva ini allow_url_fopen) pueden bloquear completamente la carga de documentos remotos.

Funciones relacionadas

• libxml_use_internal_errors() — captura errores del analizador en lugar de emitir advertencias.
• libxml_get_errors() — recupera los errores capturados.
• simplexml_load_file() — un cargador de SimpleXML que también respeta el contexto de flujo.
• Descripción general de PHP libxml — la extensión libxml en su conjunto.

Conclusión

libxml_set_streams_context() es el puente entre los contextos de flujo de PHP y los cargadores de red de libxml. Cada vez que se carga XML directamente desde una URL y se necesita autenticación, encabezados personalizados, un tiempo de espera o un proxy, crea un contexto con stream_context_create() y regístralo con esta función antes de la carga. Para archivos locales o cadenas previamente obtenidas, no es necesaria en absoluto.

Practice