Signatur
Beschreibung
In PHP können Stream-Kontexte mit zwei verschiedenen Arten von Konfigurationen versehen werden: Optionen (wrapper-spezifische Einstellungen wie HTTP-Header oder SSL-Zertifikate) und Kontextparameter. Letztere sind allgemeine, wrapper-unabhängige Einstellungen, die das grundlegende Verhalten des Kontexts selbst beeinflussen.
Der bekannteste und wichtigste Kontextparameter ist notification. Dabei handelt es sich um einen Callable, der aufgerufen wird, wenn ein Ereignis auf dem Stream auftritt – z. B. wenn Daten empfangen werden, ein Redirect stattfindet oder ein Authentifizierungsfehler auftritt. Die Callback-Funktion erhält dabei mehrere Parameter, darunter den Benachrichtigungscode ($notification_code), den Schweregrad, eine Meldung, einen Meldungscode sowie Byte-Informationen zum Fortschritt.
Kontextparameter werden als zweites Argument an stream_context_create() übergeben oder nachträglich über stream_context_set_params() gesetzt. Sie sind damit vom ersten Argument ($options) getrennt, das wrapper-spezifische Optionen enthält.
Typische Einsatzgebiete sind die Fortschrittsüberwachung bei Datei-Downloads, das Protokollieren von Verbindungsereignissen oder die benutzerdefinierte Fehlerbehandlung bei Stream-Operationen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $options | array | [] | Assoziatives Array mit wrapper-spezifischen Stream-Optionen, z. B. ['http' => ['method' => 'GET']]. |
| $params | array | [] | Assoziatives Array mit Kontextparametern. Aktuell unterstützter Parameter: notification (ein Callable, der bei Stream-Ereignissen aufgerufen wird). |
Rückgabewert
file_get_contents(), fopen() oder copy() übergeben werden kann.Beispiele
Fortschrittsüberwachung mit dem notification-Callback
<?php
function stream_notification_callback(
int $notification_code,
int $severity,
?string $message,
int $message_code,
int $bytes_transferred,
int $bytes_max
): void {
switch ($notification_code) {
case STREAM_NOTIFY_RESOLVE:
echo "Host aufgelöst.\n";
break;
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 "Empfangen: {$bytes_transferred} / {$bytes_max} Bytes\n";
break;
case STREAM_NOTIFY_COMPLETED:
echo "Download abgeschlossen.\n";
break;
case STREAM_NOTIFY_FAILURE:
echo "Fehler ({$message_code}): {$message}\n";
break;
}
}
$context = stream_context_create(
['http' => ['method' => 'GET']],
['notification' => 'stream_notification_callback']
);
$data = file_get_contents('https://www.example.com/', false, $context);
echo "Geladene Bytes: " . strlen($data) . "\n";Kontextparameter nachträglich setzen mit stream_context_set_params()
<?php
$context = stream_context_create(['http' => ['method' => 'GET']]);
// Notification-Callback nachträglich hinzufügen
stream_context_set_params($context, [
'notification' => function (
int $code,
int $severity,
?string $message,
int $msgCode,
int $transferred,
int $max
): void {
if ($code === STREAM_NOTIFY_FAILURE) {
error_log("Stream-Fehler [{$msgCode}]: {$message}");
}
}
]);
// Kontext beim Öffnen eines Streams verwenden
$fp = fopen('https://www.example.com/', 'r', false, $context);
if ($fp) {
echo stream_get_contents($fp);
fclose($fp);
}// Wichtig · Fallstricke
Wichtige Kontextparameter-Konstanten für den notification-Callback:
STREAM_NOTIFY_RESOLVE– Hostname wurde aufgelöstSTREAM_NOTIFY_CONNECT– Verbindung wurde aufgebautSTREAM_NOTIFY_AUTH_REQUIRED– Authentifizierung erforderlichSTREAM_NOTIFY_AUTH_RESULT– AuthentifizierungsergebnisSTREAM_NOTIFY_REDIRECTED– Stream wurde weitergeleitetSTREAM_NOTIFY_FILE_SIZE_IS– Dateigröße bekanntSTREAM_NOTIFY_MIME_TYPE_IS– MIME-Typ bekanntSTREAM_NOTIFY_PROGRESS– ÜbertragungsfortschrittSTREAM_NOTIFY_COMPLETED– Übertragung abgeschlossenSTREAM_NOTIFY_FAILURE– Fehler aufgetreten
Beachte, dass nicht alle Wrapper alle Benachrichtigungscodes unterstützen. HTTP- und FTP-Wrapper haben die umfangreichste Unterstützung. Bei lokal eingebundenen Dateien werden viele Ereignisse nicht ausgelöst.