libxml_set_streams_context()

La fonction libxml_set_streams_context() définit le contexte de flux que libxml utilisera la prochaine fois qu'il chargera ou écrira un document via un protocole réseau tel que HTTP, HTTPS ou FTP. C'est le point d'ancrage qui permet d'associer des en-têtes de requête personnalisés, des identifiants d'authentification, des délais d'expiration ou un proxy à la requête réseau implicite que des fonctions comme DOMDocument::load() et simplexml_load_file() effectuent en coulisse.

Cette page explique la signature, les cas d'utilisation concrets, un exemple complet et les erreurs les plus fréquentes.

Syntaxe

libxml_set_streams_context(resource $context): void

Le contexte s'applique globalement à libxml pour la requête en cours et reste actif jusqu'à ce que vous en définissiez un autre ou que le script se termine.

Quand l'utiliser ?

La plupart des chargements libxml lisent un fichier local ou une chaîne déjà récupérée, donc vous n'aurez jamais besoin de cette fonction. Vous y recourez uniquement lorsque libxml ouvre lui-même la connexion réseau — c'est-à-dire lorsque vous passez une URL http://, https:// ou ftp:// à un chargeur. Cas typiques :

• Le serveur distant exige un en-tête Authorization (authentification Basic, jeton Bearer).
• Vous avez besoin d'un User-Agent personnalisé, d'un cookie ou d'un autre en-tête de requête.
• Vous devez définir un délai d'expiration pour éviter qu'un hôte lent ne bloque votre script.
• La requête doit passer par un proxy HTTP.

Si vous récupérez vous-même le XML (par exemple avec cURL ou file_get_contents()) puis que vous analysez la chaîne résultante avec simplexml_load_string() ou DOMDocument::loadXML(), libxml ne touche jamais au réseau et cette fonction n'a aucune utilité.

Comment l'utiliser

Créez le contexte avec stream_context_create(), enregistrez-le, puis chargez votre document :

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

Comme libxml absorbe les erreurs au niveau du protocole, associez cette fonction à libxml_use_internal_errors() afin d'inspecter les échecs plutôt que d'obtenir des avertissements silencieux :

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

Consultez libxml_get_errors() pour savoir comment lire les erreurs collectées.

Erreurs fréquentes

• Elle n'affecte que les chargements réseau. L'appeler avant d'analyser un fichier local ou une chaîne en mémoire n'a aucun effet.
• Les en-têtes multiples doivent être séparés par \r\n. L'option header est une chaîne unique ; joignez les lignes avec "\r\n" (ou passez un tableau de chaînes).
• L'ordre est important. Appelez libxml_set_streams_context() avant l'appel à load() / simplexml_load_file(), pas après.
• Pas de support https:// ? Le wrapper de flux HTTPS nécessite que l'extension OpenSSL soit activée. Sans elle, libxml ne peut pas ouvrir les URL https:// du tout.
• Le chargement distant doit être autorisé. Certains paramètres de sécurité de libxml (ainsi que la directive ini allow_url_fopen) peuvent bloquer entièrement le chargement de documents distants.

Fonctions associées

• libxml_use_internal_errors() — capturer les erreurs de l'analyseur au lieu d'émettre des avertissements.
• libxml_get_errors() — récupérer ces erreurs capturées.
• simplexml_load_file() — un chargeur SimpleXML qui respecte également le contexte de flux.
• Vue d'ensemble de PHP libxml — l'extension libxml dans son ensemble.

Conclusion

libxml_set_streams_context() est le pont entre les contextes de flux PHP et les chargeurs réseau de libxml. Chaque fois que vous chargez du XML directement depuis une URL et que vous avez besoin d'une authentification, d'en-têtes personnalisés, d'un délai d'expiration ou d'un proxy, créez un contexte avec stream_context_create() et enregistrez-le avec cette fonction avant le chargement. Pour les fichiers locaux ou les chaînes pré-récupérées, vous n'en avez pas besoin du tout.

Pratique