libxml_set_streams_context()

La funzione libxml_set_streams_context() imposta il contesto di stream che libxml utilizzerà la prossima volta che caricherà o scriverà un documento tramite un protocollo di rete come HTTP, HTTPS o FTP. È il meccanismo che permette di allegare intestazioni di richiesta personalizzate, credenziali di autenticazione, timeout o un proxy alla richiesta di rete implicita che funzioni come DOMDocument::load() e simplexml_load_file() eseguono in background.

Questa pagina illustra la firma della funzione, quando è effettivamente necessaria, un esempio completo funzionante e le problematiche più comuni.

Sintassi

libxml_set_streams_context(resource $context): void

Il contesto si applica globalmente a libxml per la richiesta corrente e rimane attivo fino a quando non se ne imposta uno diverso o lo script termina.

Quando utilizzarla?

La maggior parte dei caricamenti libxml legge un file locale o una stringa già recuperata, quindi questa funzione non è necessaria. La si utilizza solo quando libxml apre direttamente la connessione di rete — ovvero quando si passa un URL http://, https:// o ftp:// a un loader. Casi tipici:

• Il server remoto richiede un'intestazione Authorization (autenticazione Basic, un bearer token).
• È necessario un User-Agent personalizzato, un cookie o un'altra intestazione di richiesta.
• Bisogna impostare un timeout per evitare che un host lento blocchi lo script.
• La richiesta deve passare attraverso un proxy HTTP.

Se si recupera l'XML autonomamente (ad esempio con cURL o file_get_contents()) e poi si analizza la stringa risultante con simplexml_load_string() o DOMDocument::loadXML(), libxml non tocca mai la rete e questa funzione non ha alcun effetto utile.

Come utilizzarla

Creare il contesto con stream_context_create(), registrarlo, quindi caricare il 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;
?>

Poiché libxml nasconde gli errori a livello di protocollo, abbinare questa funzione a libxml_use_internal_errors() per poter ispezionare i fallimenti invece di ricevere avvisi silenziosi:

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

Vedere libxml_get_errors() per come leggere gli errori raccolti.

Problematiche comuni

• Influisce solo sui caricamenti di rete. Chiamarla prima di analizzare un file locale o una stringa in memoria non ha alcun effetto.
• Più intestazioni devono essere separate da \r\n. L'opzione header è una singola stringa; unire le righe con "\r\n" (o passare un array di stringhe).
• L'ordine è importante. Chiamare libxml_set_streams_context() prima della chiamata load() / simplexml_load_file(), non dopo.
• Nessun supporto per https://? Il wrapper di stream HTTPS richiede che l'estensione OpenSSL sia abilitata. Senza di essa, libxml non può aprire URL https:// in alcun modo.
• Il caricamento remoto deve essere consentito. Alcune impostazioni di sicurezza di libxml (e la direttiva ini allow_url_fopen) possono bloccare completamente il caricamento di documenti remoti.

Funzioni correlate

• libxml_use_internal_errors() — acquisire gli errori del parser invece di emettere avvisi.
• libxml_get_errors() — recuperare gli errori acquisiti.
• simplexml_load_file() — un loader SimpleXML che rispetta anche il contesto di stream.
• Panoramica PHP libxml — l'estensione libxml nel suo insieme.

Conclusione

libxml_set_streams_context() è il collegamento tra i contesti di stream di PHP e i loader di rete di libxml. Ogni volta che si carica XML direttamente da un URL e si ha bisogno di autenticazione, intestazioni personalizzate, un timeout o un proxy, creare un contesto con stream_context_create() e registrarlo con questa funzione prima del caricamento. Per file locali o stringhe pre-recuperate, non è necessaria.

Esercizio