Signatur
Beschreibung
stream_notification_callback ist keine eigenständige PHP-Funktion, sondern beschreibt die Signatur, die eine benutzerdefinierte Callback-Funktion haben muss, um als notification-Callback in einem Stream-Kontext (stream_context_create()) eingesetzt zu werden. Der Callback wird vom PHP-Stream-System automatisch aufgerufen, sobald ein Stream-Ereignis eintritt – etwa beim Verbindungsaufbau, beim Datenempfang oder bei einem Fehler.
Der Callback empfängt sechs Parameter: den Ereigniscode ($notification_code), einen Schweregrad ($severity), eine optionale Nachricht ($message), einen nachrichtenspezifischen Code ($message_code) sowie Informationen über den Fortschritt des Datentransfers ($bytes_transferred und $bytes_max). Damit lässt sich z. B. ein Fortschrittsbalken für HTTP-Downloads implementieren.
Der $notification_code ist eine der STREAM_NOTIFY_*-Konstanten (z. B. STREAM_NOTIFY_PROGRESS, STREAM_NOTIFY_CONNECT, STREAM_NOTIFY_FAILURE). Der $severity ist eine der STREAM_NOTIFY_SEVERITY_*-Konstanten (STREAM_NOTIFY_SEVERITY_INFO, STREAM_NOTIFY_SEVERITY_WARN, STREAM_NOTIFY_SEVERITY_ERR).
Typische Einsatzgebiete sind Fortschrittsanzeigen bei Datei-Downloads per HTTP oder FTP, Fehlerprotokollierung auf Stream-Ebene sowie das Überwachen von Verbindungsereignissen ohne eigene Schleifenlogik.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $notification_code Pflicht | int | Eine der STREAM_NOTIFY_*-Konstanten, die das eingetretene Ereignis beschreibt (z. B. STREAM_NOTIFY_CONNECT, STREAM_NOTIFY_PROGRESS, STREAM_NOTIFY_FAILURE). |
|
| $severity Pflicht | int | Schweregrad des Ereignisses als eine der STREAM_NOTIFY_SEVERITY_*-Konstanten: STREAM_NOTIFY_SEVERITY_INFO, STREAM_NOTIFY_SEVERITY_WARN oder STREAM_NOTIFY_SEVERITY_ERR. |
|
| $message Pflicht | ?string | Eine optionale, vom Stream-Wrapper bereitgestellte Nachricht zum Ereignis. Kann null sein, wenn keine Nachricht vorhanden ist. |
|
| $message_code Pflicht | int | Ein wrapper-spezifischer Nachrichtencode (z. B. HTTP-Statuscode). Bedeutung und Wert hängen vom jeweiligen Stream-Wrapper ab. | |
| $bytes_transferred Pflicht | int | Anzahl der bisher übertragenen Bytes. Relevant bei STREAM_NOTIFY_PROGRESS-Ereignissen. |
|
| $bytes_max Pflicht | int | Gesamtanzahl der zu übertragenden Bytes (z. B. aus dem Content-Length-Header). Ist 0, wenn die Gesamtgröße unbekannt ist. |
Rückgabewert
Beispiele
Fortschrittsanzeige beim HTTP-Download
<?php
function downloadProgress(
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:
if ($bytes_max > 0) {
$percent = round(($bytes_transferred / $bytes_max) * 100, 1);
echo "Fortschritt: {$bytes_transferred}/{$bytes_max} Bytes ({$percent}%)\n";
}
break;
case STREAM_NOTIFY_COMPLETED:
echo "Download abgeschlossen.\n";
break;
case STREAM_NOTIFY_FAILURE:
echo "Fehler (HTTP {$message_code}): {$message}\n";
break;
}
}
$context = stream_context_create(
['http' => ['method' => 'GET']],
['notification' => 'downloadProgress']
);
$data = file_get_contents('https://example.com/file.txt', false, $context);
if ($data !== false) {
echo "Empfangene Bytes: " . strlen($data) . "\n";
}Fehlerprotokollierung per Closure
<?php
$logger = [];
$notificationCallback = function (
int $notification_code,
int $severity,
?string $message,
int $message_code,
int $bytes_transferred,
int $bytes_max
) use (&$logger): void {
if ($severity === STREAM_NOTIFY_SEVERITY_ERR) {
$logger[] = [
'code' => $notification_code,
'http' => $message_code,
'message' => $message,
];
}
};
$context = stream_context_create(
['http' => ['method' => 'GET', 'ignore_errors' => true]],
['notification' => $notificationCallback]
);
@file_get_contents('https://example.com/nicht-vorhanden', false, $context);
if (!empty($logger)) {
foreach ($logger as $entry) {
echo "Stream-Fehler – HTTP {$entry['http']}: {$entry['message']}\n";
}
} else {
echo "Keine Fehler aufgetreten.\n";
}// Wichtig · Fallstricke
Wichtig: Der Callback muss exakt die vorgegebene Signatur mit sechs Parametern implementieren, da das Stream-System ihn mit genau diesen Argumenten aufruft. Eine abweichende Signatur kann zu Warnungen oder unerwartetem Verhalten führen.
Der notification-Kontextparameter wird beim Aufruf von stream_context_create() als zweites Argument (Optionen, nicht Parameter) übergeben – also nicht unter den wrapper-spezifischen Optionen im ersten Array, sondern im separaten Optionen-Array: stream_context_create($options, ['notification' => $callback]).
Nicht alle Stream-Wrapper unterstützen alle STREAM_NOTIFY_*-Ereignisse. Der HTTP-Wrapper liefert z. B. STREAM_NOTIFY_FILE_SIZE_IS nur, wenn der Server einen Content-Length-Header sendet. Bei komprimierten Antworten (gzip) kann $bytes_max von der tatsächlichen Inhaltslänge abweichen.
Für interaktive Fortschrittsanzeigen in CLI-Skripten empfiehlt sich, den Output-Buffer zu deaktivieren oder regelmäßig zu leeren (ob_flush(), flush()), damit die Ausgaben sofort sichtbar sind.