libxml_set_streams_context()

Die Funktion libxml_set_streams_context() setzt den Stream-Kontext, den libxml beim nächsten Laden oder Schreiben eines Dokuments über ein Netzwerkprotokoll wie HTTP, HTTPS oder FTP verwendet. Sie ist der Einstiegspunkt, über den Sie benutzerdefinierte Anfrage-Header, Authentifizierungsdaten, Timeouts oder einen Proxy an die implizite Netzwerkanfrage anhängen können, die Funktionen wie DOMDocument::load() und simplexml_load_file() im Hintergrund durchführen.

Diese Seite erläutert die Signatur, wann Sie die Funktion tatsächlich benötigen, ein vollständiges Arbeitsbeispiel sowie die häufigsten Fallstricke.

Syntax

libxml_set_streams_context(resource $context): void

Der Kontext wird für libxml für die aktuelle Anfrage global gesetzt und bleibt wirksam, bis Sie einen anderen setzen oder das Skript endet.

Wann wird die Funktion benötigt?

Die meisten libxml-Ladevorgänge lesen eine lokale Datei oder einen bereits abgerufenen String, sodass Sie diese Funktion nie benötigen. Sie greifen nur dann darauf zurück, wenn libxml selbst die Netzwerkverbindung öffnet — d. h. Sie übergeben eine http://-, https://- oder ftp://-URL an einen Loader. Typische Anwendungsfälle:

• Der Remote-Server erfordert einen Authorization-Header (Basic Auth, ein Bearer-Token).
• Sie benötigen einen benutzerdefinierten User-Agent, ein Cookie oder einen anderen Anfrage-Header.
• Sie müssen ein Timeout setzen, damit ein langsamer Host Ihr Skript nicht blockiert.
• Die Anfrage muss über einen HTTP-Proxy geleitet werden.

Wenn Sie das XML selbst abrufen (z. B. mit cURL oder file_get_contents()) und dann den resultierenden String mit simplexml_load_string() oder DOMDocument::loadXML() parsen, berührt libxml das Netzwerk nie, und diese Funktion hat keinen nützlichen Effekt.

Verwendung

Erstellen Sie den Kontext mit stream_context_create(), registrieren Sie ihn und laden Sie dann Ihr Dokument:

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

Da libxml Fehler auf Protokollebene verschluckt, kombinieren Sie dies mit libxml_use_internal_errors(), damit Sie Fehler untersuchen können, anstatt stille Warnungen zu erhalten:

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

Unter libxml_get_errors() erfahren Sie, wie Sie die gesammelten Fehler auslesen.

Häufige Fallstricke

• Sie betrifft nur Netzwerkladevorgänge. Der Aufruf vor dem Parsen einer lokalen Datei oder eines In-Memory-Strings hat keinen Effekt.
• Mehrere Header müssen durch \r\n getrennt werden. Die Option header ist ein einzelner String; verbinden Sie Zeilen mit "\r\n" (oder übergeben Sie ein Array von Strings).
• Die Reihenfolge ist wichtig. Rufen Sie libxml_set_streams_context() vor dem load()- / simplexml_load_file()-Aufruf auf, nicht danach.
• Kein https://-Support? Der HTTPS-Stream-Wrapper erfordert, dass die OpenSSL-Erweiterung aktiviert ist. Ohne sie kann libxml https://-URLs überhaupt nicht öffnen.
• Remote-Laden muss erlaubt sein. Einige libxml-Sicherheitseinstellungen (und die allow_url_fopen-ini-Direktive) können das Laden entfernter Dokumente vollständig blockieren.

Verwandte Funktionen

• libxml_use_internal_errors() — Parser-Fehler erfassen, anstatt Warnungen auszugeben.
• libxml_get_errors() — die erfassten Fehler abrufen.
• simplexml_load_file() — ein SimpleXML-Loader, der den Stream-Kontext ebenfalls berücksichtigt.
• PHP libxml-Übersicht — die übergeordnete libxml-Erweiterung.

Fazit

libxml_set_streams_context() ist die Brücke zwischen PHPs Stream-Kontexten und libxmls Netzwerk-Loadern. Wann immer Sie XML direkt von einer URL laden und Authentifizierung, benutzerdefinierte Header, ein Timeout oder einen Proxy benötigen, erstellen Sie einen Kontext mit stream_context_create() und registrieren Sie ihn mit dieser Funktion vor dem Laden. Für lokale Dateien oder vorab abgerufene Strings benötigen Sie sie überhaupt nicht.

Übung