Signatur
Beschreibung
stream_context_set_params() ermöglicht es, nach der Erstellung eines Stream-Kontextes allgemeine Parameter zu setzen oder zu aktualisieren. Im Gegensatz zu stream_context_set_option(), das wrapper-spezifische Optionen verwaltet, steuert diese Funktion übergeordnete Verhaltensaspekte des Kontextes selbst – insbesondere die Angabe einer Benachrichtigungs-Callback-Funktion (notification).
Der Parameter-Array kann den Schlüssel notification enthalten, dessen Wert ein Callable sein muss. Diese Callback-Funktion wird vom Stream-Wrapper aufgerufen, wenn bestimmte Ereignisse eintreten – beispielsweise beim Fortschritt eines HTTP-Downloads, bei Verbindungsaufbau oder Weiterleitungen. Das ist besonders nützlich, um Fortschrittsanzeigen zu implementieren oder Transferdetails zu protokollieren.
Zusätzlich kann der Parameter-Array den Schlüssel options enthalten, um wrapper-spezifische Optionen direkt mit zu übergeben – dies ist äquivalent zum Aufruf von stream_context_set_option().
Die Funktion eignet sich hervorragend in Situationen, in denen ein Kontext-Handle bereits erstellt und möglicherweise weitergegeben wurde, aber nachträglich mit einem Benachrichtigungs-Callback ausgestattet werden soll, ohne den Kontext neu erstellen zu müssen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $context Pflicht | resource | Ein gültiges Stream-Kontext-Handle, das z. B. mit stream_context_create() erzeugt wurde. |
|
| $params Pflicht | array | Assoziatives Array mit Kontext-Parametern. Unterstützte Schlüssel:
|
Rückgabewert
true bei Erfolg zurück, false bei einem Fehler (z. B. wenn $context kein gültiger Kontext ist).Beispiele
Benachrichtigungs-Callback für HTTP-Download setzen
<?php
function mein_callback(int $notification_code, int $severity, ?string $message, int $message_code, int $bytes_transferred, int $bytes_max): void
{
switch ($notification_code) {
case STREAM_NOTIFY_CONNECT:
echo "Verbindung hergestellt.\n";
break;
case STREAM_NOTIFY_FILE_SIZE_IS:
echo "Dateigröße: {$bytes_max} Bytes\n";
break;
case STREAM_NOTIFY_PROGRESS:
echo "Fortschritt: {$bytes_transferred} / {$bytes_max} Bytes\n";
break;
case STREAM_NOTIFY_COMPLETED:
echo "Transfer abgeschlossen.\n";
break;
}
}
$context = stream_context_create();
stream_context_set_params($context, [
'notification' => 'mein_callback',
]);
$fp = fopen('http://example.com/', 'r', false, $context);
if ($fp) {
stream_get_contents($fp);
fclose($fp);
}Nachträgliches Setzen von Optionen und Callback
<?php
$context = stream_context_create([
'http' => [
'method' => 'GET',
],
]);
// Nachträglich Timeout und Callback ergänzen
stream_context_set_params($context, [
'notification' => function (int $code, int $severity, ?string $msg, int $msgCode, int $transferred, int $max): void {
if ($code === STREAM_NOTIFY_PROGRESS && $max > 0) {
$prozent = round($transferred / $max * 100, 1);
echo "Laden: {$prozent}%\n";
}
},
'options' => [
'http' => [
'timeout' => 10,
'user_agent' => 'MeinPHP-Client/1.0',
],
],
]);
$inhalt = file_get_contents('http://example.com/', false, $context);
echo strlen($inhalt) . " Bytes geladen.\n";// Wichtig · Fallstricke
Callback-Signatur: Die als notification angegebene Funktion muss folgende Signatur einhalten: function(int $notification_code, int $severity, ?string $message, int $message_code, int $bytes_transferred, int $bytes_max): void. Wird eine falsche Signatur übergeben, kann es zu Laufzeitfehlern oder stillschweigendem Ignorieren des Callbacks kommen.
Wrapper-Unterstützung: Nicht alle Stream-Wrapper lösen Benachrichtigungen aus. Insbesondere der file://-Wrapper sendet kaum Ereignisse. Am zuverlässigsten funktionieren Callbacks mit dem http://- und ftp://-Wrapper.
Unterschied zu stream_context_set_option(): Diese Funktion setzt wrapper-spezifische Optionen, während stream_context_set_params() für kontextweite Parameter (v. a. den Callback) gedacht ist. Beide können jedoch kombiniert werden, indem options im $params-Array mitgegeben wird.