stream_context_set_options — Funktion · PHP-Referenz

Signatur

stream_context_set_options(resource $context, array $options): bool

Beschreibung

stream_context_set_options() weist einem vorhandenen Stream-Kontext (erzeugt z. B. mit stream_context_create()) einen neuen Satz von Optionen zu. Anders als stream_context_set_option() (die einzelne Optionen setzt) ersetzt diese Funktion alle Optionen des Kontexts auf einmal durch das übergebene Array.

Das Optionen-Array hat dieselbe Struktur wie das erste Argument von stream_context_create(): ein assoziatives Array, dessen Schlüssel den Wrapper-Namen entsprechen (http, ssl, ftp usw.), und dessen Werte wiederum assoziative Arrays mit den jeweiligen Wrapper-spezifischen Optionen sind.

Typische Anwendungsfälle sind das nachträgliche Anpassen eines Kontexts vor einem HTTP-Request, das Setzen von SSL-Zertifikatspfaden oder das Konfigurieren von FTP-Verbindungsparametern, wenn der Kontext bereits erstellt wurde und weiterverwendet werden soll.

Hinweis: Diese Funktion wurde in PHP 8.3 eingeführt und ersetzt das frühere Muster, bei dem stream_context_set_option() mit einem Array als zweitem Argument aufgerufen wurde. Für ältere PHP-Versionen sollte stattdessen stream_context_set_option() mit drei Argumenten oder stream_context_create() verwendet werden.

Parameter

Name	Typ	Default	Beschreibung
$context Pflicht	resource		Eine gültige Stream-Kontext-Ressource, wie sie von `stream_context_create()` zurückgegeben wird.
$options Pflicht	array		Ein assoziatives Array der Form `['wrapper' => ['option' => 'wert']]`. Alle bisherigen Optionen des Kontexts werden durch dieses Array ersetzt.

Rückgabewert

Typ

bool

Beschreibung

Gibt true bei Erfolg zurück, false bei einem Fehler (z. B. wenn $context keine gültige Kontext-Ressource ist).

Beispiele

HTTP-Kontext nachträglich mit neuen Optionen konfigurieren

<?php
// Kontext erstellen
$context = stream_context_create();

// Optionen nachträglich vollständig setzen
stream_context_set_options($context, [
    'http' => [
        'method'  => 'POST',
        'header'  => "Content-Type: application/json\r\n",
        'content' => json_encode(['key' => 'value']),
        'timeout' => 10,
    ],
]);

$response = file_get_contents('https://httpbin.org/post', false, $context);
if ($response !== false) {
    $data = json_decode($response, true);
    echo 'Antwort erhalten: ' . $data['url'] . PHP_EOL;
} else {
    echo 'Anfrage fehlgeschlagen.' . PHP_EOL;
}

Antwort erhalten: https://httpbin.org/post

SSL-Kontext für eine sichere Verbindung konfigurieren

<?php
$context = stream_context_create();

// SSL-Optionen vollständig setzen
$success = stream_context_set_options($context, [
    'ssl' => [
        'verify_peer'       => true,
        'verify_peer_name'  => true,
        'cafile'            => '/etc/ssl/certs/ca-certificates.crt',
        'allow_self_signed' => false,
    ],
    'http' => [
        'method'  => 'GET',
        'timeout' => 5,
    ],
]);

if ($success) {
    echo 'Kontext-Optionen erfolgreich gesetzt.' . PHP_EOL;
    $response = file_get_contents('https://example.com', false, $context);
    echo 'Status: ' . ($response !== false ? 'OK' : 'Fehler') . PHP_EOL;
} else {
    echo 'Fehler beim Setzen der Optionen.' . PHP_EOL;
}

Kontext-Optionen erfolgreich gesetzt. Status: OK

// Wichtig · Fallstricke

Achtung: Diese Funktion ersetzt alle vorhandenen Optionen des Kontexts vollständig. Sollen nur einzelne Optionen geändert werden, ohne andere zu überschreiben, empfiehlt sich der Einsatz von stream_context_get_options(), um zunächst die vorhandenen Optionen auszulesen, diese zu modifizieren und dann mit stream_context_set_options() zurückzuschreiben.

Für Versionen vor PHP 8.3 existiert diese Funktion nicht. Dort kann stream_context_set_option($context, $optionsArray) (mit Array als zweitem Argument, ohne drittes Argument) als funktionales Äquivalent verwendet werden – dieses Verhalten war in älteren PHP-Versionen undokumentiert, aber vorhanden.

Bei sicherheitskritischen SSL-Verbindungen sollte verify_peer niemals auf false gesetzt werden, da dies Man-in-the-Middle-Angriffe ermöglicht.

Siehe auch

stream_context_create stream_context_set_option stream_context_get_options stream_context_set_params file_get_contents