stream_context_set_option — Funktion · PHP-Referenz

Signatur

stream_context_set_option(resource $context, array|string $wrapper_or_options, string $optionname = null, mixed $value = null): bool

Beschreibung

stream_context_set_option() ermöglicht es, Optionen für einen bestehenden Stream-Kontext nachträglich zu setzen oder zu aktualisieren. Stream-Kontexte werden verwendet, um das Verhalten von Datei- und Netzwerk-Streams zu steuern – etwa HTTP-Header bei file_get_contents(), SSL-Einstellungen oder FTP-Optionen.

Die Funktion kann auf zwei Arten aufgerufen werden: Entweder übergibt man als zweiten Parameter ein assoziatives Array der Form ['wrapper' => ['option' => 'wert']], oder man übergibt Wrapper-Name, Options-Name und Wert als einzelne Parameter. Beide Varianten sind seit PHP 5 verfügbar, wobei die Array-Variante mehrere Optionen gleichzeitig setzen kann.

Typische Anwendungsfälle sind das Setzen von HTTP-Methode, Headern und Body für HTTP-Wrapper, das Konfigurieren von SSL-Zertifikaten oder das Anpassen von Timeout-Werten. Optionen werden immer einem konkreten Wrapper (http, ftp, ssl usw.) zugeordnet.

Der Kontext muss zuvor mit stream_context_create() oder stream_context_get_default() erzeugt worden sein. Änderungen wirken sich auf alle nachfolgenden Stream-Operationen aus, die diesen Kontext verwenden.

Parameter

Name	Typ	Default	Beschreibung
$context Pflicht	resource		Ein Stream-Kontext, wie er von `stream_context_create()` zurückgegeben wird.
$wrapper_or_options Pflicht	array\|string		Entweder ein assoziatives Array mit Wrapper-Namen als Schlüssel und den jeweiligen Optionen als Wert (z. B. `['http' => ['method' => 'POST']]`), oder der Name des Wrappers als Zeichenkette, wenn `optionname` und `value` separat angegeben werden.
$optionname	string	null	Name der Option, die gesetzt werden soll. Nur relevant, wenn `wrapper_or_options` ein Wrapper-Name (String) ist.
$value	mixed	null	Wert der Option. Nur relevant, wenn `wrapper_or_options` ein Wrapper-Name (String) ist.

Rückgabewert

Typ

bool

Beschreibung

Gibt true bei Erfolg zurück, false bei einem Fehler (z. B. ungültiger Kontext).

Beispiele

HTTP-POST-Anfrage mit stream_context_set_option konfigurieren

<?php
$context = stream_context_create();

$postData = http_build_query(['user' => 'max', 'token' => 'abc123']);

// Optionen als Array setzen
stream_context_set_option($context, [
    'http' => [
        'method'  => 'POST',
        'header'  => "Content-Type: application/x-www-form-urlencoded\r\nAccept: application/json",
        'content' => $postData,
        'timeout' => 10,
    ]
]);

$response = file_get_contents('https://httpbin.org/post', false, $context);

if ($response !== false) {
    $data = json_decode($response, true);
    echo 'Gesendet: ' . print_r($data['form'] ?? [], true);
} else {
    echo 'Anfrage fehlgeschlagen.';
}

Gesendet: Array ( [token] => abc123 [user] => max )

SSL-Optionen und einzelne Option nachträglich hinzufügen

<?php
// Kontext mit SSL-Optionen erstellen
$context = stream_context_create([
    'ssl' => [
        'verify_peer'      => true,
        'verify_peer_name' => true,
    ]
]);

// Einzelne Option nachträglich per String-Syntax setzen
stream_context_set_option($context, 'ssl', 'cafile', '/etc/ssl/certs/ca-certificates.crt');

// HTTP-Optionen ergänzen
stream_context_set_option($context, 'http', 'method', 'GET');
stream_context_set_option($context, 'http', 'header', 'Accept: text/html');

$opts = stream_context_get_options($context);
echo 'SSL verify_peer: ' . ($opts['ssl']['verify_peer'] ? 'ja' : 'nein') . PHP_EOL;
echo 'HTTP-Methode: ' . $opts['http']['method'] . PHP_EOL;

SSL verify_peer: ja HTTP-Methode: GET

// Wichtig · Fallstricke

Sicherheit: Beim Abrufen externer URLs über den HTTP-Wrapper sollte verify_peer und verify_peer_name im SSL-Kontext niemals auf false gesetzt werden – andernfalls sind Man-in-the-Middle-Angriffe möglich.

Kompatibilität: Ab PHP 8.0 wurde die Signatur präzisiert. Wenn wrapper_or_options ein Array ist, dürfen optionname und value nicht übergeben werden. In älteren PHP-Versionen war dieses Verhalten weniger strikt dokumentiert.

Aliase: stream_context_set_option() ist ein Alias für stream_context_set_params() in Bezug auf Context-Parameter – beide Funktionen sind aber konzeptuell verschieden. stream_context_set_params() setzt Kontext-Parameter (wie Callback-Funktionen), während stream_context_set_option() Wrapper-spezifische Optionen setzt.

Siehe auch

stream_context_create stream_context_get_options stream_context_get_default stream_context_set_params file_get_contents fopen