stream_get_meta_data — Funktion · PHP-Referenz

Signatur

stream_get_meta_data(resource $stream): array

Beschreibung

stream_get_meta_data() gibt detaillierte Informationen über einen geöffneten Stream zurück. Dazu gehören Angaben zum Wrapper-Typ, dem verwendeten Stream-Modus, ob der Stream lesbar oder schreibbar ist, ob ein Timeout aufgetreten ist, ob das Dateiende (EOF) erreicht wurde, sowie optional HTTP-Header, die beim Öffnen des Streams empfangen wurden.

Die Funktion ist besonders nützlich beim Arbeiten mit Netzwerk-Streams (z. B. via fopen() mit HTTP/FTP-Wrapper), da man darüber empfangene HTTP-Response-Header auslesen kann. Aber auch bei lokalen Datei-Streams liefert sie hilfreiche Informationen wie den Dateipfad und den Öffnungsmodus.

Typische Anwendungsfälle sind: Prüfen, ob ein Stream geblockt ist (blocked), ob ein Timeout beim Lesen aufgetreten ist (timed_out), oder das Auslesen von HTTP-Headern ohne cURL bei einfachen HTTP-Anfragen (wrapper_data). Außerdem kann man über seekable prüfen, ob Positionierungsoperationen wie fseek() auf dem Stream möglich sind.

Das zurückgegebene Array enthält immer die Schlüssel timed_out, blocked, eof, unread_bytes, stream_type, wrapper_type, wrapper_data, mode, seekable und uri. Je nach Wrapper und Stream-Typ können zusätzliche Einträge vorhanden sein.

Parameter

Name	Typ	Default	Beschreibung
$stream Pflicht	resource		Ein gültiger Stream-Ressource-Handle, z. B. zurückgegeben von `fopen()`, `fsockopen()` oder `stream_socket_client()`.

Rückgabewert

Typ

array

Beschreibung

Gibt ein assoziatives Array mit folgenden Schlüsseln zurück:

timed_out (bool): true, wenn beim letzten Lesevorgang ein Timeout aufgetreten ist.
blocked (bool): true, wenn der Stream im blockierenden Modus ist.
eof (bool): true, wenn das Ende des Streams erreicht wurde.
unread_bytes (int): Anzahl der Bytes, die sich noch im internen Puffer des Streams befinden.
stream_type (string): Interne Bezeichnung des Stream-Typs (z. B. tcp_socket/ssl).
wrapper_type (string): Name des verwendeten Wrappers (z. B. http, ftp, plainfile).
wrapper_data (mixed): Zusätzliche Daten des Wrappers. Bei HTTP-Streams ein Array der empfangenen Response-Header.
mode (string): Öffnungsmodus des Streams (z. B. r, r+, w).
seekable (bool): true, wenn Positionierungsoperationen auf dem Stream möglich sind.
uri (string): Die URI oder der Dateipfad des Streams.

Beispiele

HTTP-Response-Header über Stream-Metadaten auslesen

<?php
$stream = fopen('https://www.example.com/', 'r');
if ($stream === false) {
    die('Stream konnte nicht geöffnet werden.');
}

$meta = stream_get_meta_data($stream);
fclose($stream);

// HTTP-Header aus wrapper_data auslesen
if (isset($meta['wrapper_data'])) {
    echo "Empfangene HTTP-Header:" . PHP_EOL;
    foreach ($meta['wrapper_data'] as $header) {
        echo $header . PHP_EOL;
    }
}

// Wrapper-Typ ausgeben
echo "Wrapper-Typ: " . $meta['wrapper_type'] . PHP_EOL;
echo "Stream-Typ: " . $meta['stream_type'] . PHP_EOL;

Empfangene HTTP-Header: HTTP/1.1 200 OK Content-Type: text/html; charset=UTF-8 ... Wrapper-Typ: http Stream-Typ: tcp_socket/ssl

Timeout-Erkennung bei Socket-Verbindungen

<?php
$socket = fsockopen('tcp://www.example.com', 80, $errno, $errstr, 5);
if ($socket === false) {
    die("Verbindungsfehler [$errno]: $errstr");
}

// Timeout auf 2 Sekunden setzen
stream_set_timeout($socket, 2);

// Anfrage senden
fwrite($socket, "GET / HTTP/1.0\r\nHost: www.example.com\r\n\r\n");

// Antwort lesen
$response = '';
while (!feof($socket)) {
    $response .= fgets($socket, 4096);
    $meta = stream_get_meta_data($socket);
    if ($meta['timed_out']) {
        echo "Timeout beim Lesen des Streams aufgetreten!" . PHP_EOL;
        break;
    }
}

fclose($socket);

echo "Seekable: " . ($meta['seekable'] ? 'ja' : 'nein') . PHP_EOL;
echo "Blocked:  " . ($meta['blocked']  ? 'ja' : 'nein') . PHP_EOL;

Seekable: nein Blocked: ja

Metadaten eines lokalen Datei-Streams prüfen

<?php
$file = fopen('/tmp/testdatei.txt', 'w+');
if ($file === false) {
    die('Datei konnte nicht geöffnet werden.');
}

$meta = stream_get_meta_data($file);

echo "URI:          " . $meta['uri']          . PHP_EOL;
echo "Modus:        " . $meta['mode']         . PHP_EOL;
echo "Seekable:     " . ($meta['seekable'] ? 'ja' : 'nein') . PHP_EOL;
echo "Wrapper-Typ:  " . $meta['wrapper_type'] . PHP_EOL;
echo "Stream-Typ:   " . $meta['stream_type']  . PHP_EOL;

fclose($file);

URI: /tmp/testdatei.txt Modus: w+ Seekaable: ja Wrapper-Typ: plainfile Stream-Typ: STDIO

// Wichtig · Fallstricke

Wichtig: Der Schlüssel wrapper_data enthält nur dann HTTP-Header, wenn der Stream über den HTTP-Wrapper geöffnet wurde (z. B. fopen('http://...', 'r')). Bei anderen Wrappern enthält er möglicherweise andere Daten oder ist leer.

Achtung bei unread_bytes: Dieser Wert gibt nur die Bytes im internen PHP-Puffer an, nicht die tatsächlich noch auf der Gegenstelle verfügbaren Daten. Er ist deshalb nur bedingt aussagekräftig.

Sicherheitshinweis: Beim Auslesen von HTTP-Headern über wrapper_data bei externen URLs sollten die Inhalte stets als nicht vertrauenswürdig betrachtet und ggf. validiert werden, bevor sie weiterverarbeitet werden.

Siehe auch

fopen stream_set_timeout stream_set_blocking stream_context_create fsockopen feof