ssh2_fetch_stream — Funktion · PHP-Referenz

Signatur

ssh2_fetch_stream(resource $channel, int $streamid): resource|false

Beschreibung

ssh2_fetch_stream() ermöglicht es, einen zusätzlichen Datenstrom aus einem bereits geöffneten SSH2-Kanal zu beziehen. Am häufigsten wird die Funktion verwendet, um den stderr-Stream eines Befehls abzurufen, der über ssh2_exec() ausgeführt wurde. Damit können Standardausgabe und Fehlerausgabe getrennt voneinander gelesen werden.

Als zweiter Parameter wird eine der vordefinierten Konstanten übergeben, die den gewünschten Sub-Stream identifiziert. Typischerweise ist das SSH2_STREAM_STDERR (Wert 1) oder SSH2_STREAM_STDIO (Wert 0).

Der zurückgegebene Datenstrom verhält sich wie ein normaler PHP-Stream und kann mit den üblichen Stream-Funktionen wie stream_get_contents() oder fread() ausgelesen werden. Um korrekte Ergebnisse zu erhalten, sollte der Kanal zuvor mit stream_set_blocking() in den blockierenden Modus versetzt werden.

Diese Funktion ist Teil der PECL-Erweiterung ssh2 und steht daher nur zur Verfügung, wenn diese Erweiterung installiert und aktiviert ist.

Parameter

Name	Typ	Default	Beschreibung
$channel Pflicht	resource		Ein SSH2-Kanal-Resource, der zuvor z. B. mit `ssh2_exec()` geöffnet wurde.
$streamid Pflicht	int		Die ID des gewünschten Sub-Streams. Verwende `SSH2_STREAM_STDIO` (0) für stdout oder `SSH2_STREAM_STDERR` (1) für stderr.

Rückgabewert

Typ

resource|false

Beschreibung

Gibt eine Stream-Resource zurück, die mit Standard-PHP-Stream-Funktionen gelesen werden kann. Bei einem Fehler wird false zurückgegeben.

Beispiele

stdout und stderr eines SSH2-Befehls getrennt lesen

<?php
// Verbindung aufbauen
$connection = ssh2_connect('beispiel-server.de', 22);
ssh2_auth_password($connection, 'benutzer', 'geheimesPasswort');

// Befehl ausführen
$channel = ssh2_exec($connection, 'ls /nicht-vorhanden 2>&1; echo "Hallo"');

// Blockierenden Modus aktivieren
stream_set_blocking($channel, true);

// stdout-Stream lesen
$stdout = stream_get_contents($channel);

// stderr-Stream über ssh2_fetch_stream abrufen
$stderrStream = ssh2_fetch_stream($channel, SSH2_STREAM_STDERR);
stream_set_blocking($stderrStream, true);
$stderr = stream_get_contents($stderrStream);

echo "STDOUT: " . $stdout . PHP_EOL;
echo "STDERR: " . $stderr . PHP_EOL;

fclose($channel);
fclose($stderrStream);

STDOUT: Hallo STDERR: ls: /nicht-vorhanden: No such file or directory

Nur den stderr-Stream eines Remote-Befehls prüfen

<?php
$connection = ssh2_connect('beispiel-server.de', 22);
ssh2_auth_pubkey_file(
    $connection,
    'benutzer',
    '/home/benutzer/.ssh/id_rsa.pub',
    '/home/benutzer/.ssh/id_rsa'
);

$channel = ssh2_exec($connection, 'php -r "trigger_error(\"Testfehler\", E_USER_ERROR);"');

$stderrStream = ssh2_fetch_stream($channel, SSH2_STREAM_STDERR);
stream_set_blocking($stderrStream, true);

$fehlerausgabe = stream_get_contents($stderrStream);

if (!empty($fehlerausgabe)) {
    echo "Fehler auf dem Remote-System: " . $fehlerausgabe . PHP_EOL;
} else {
    echo "Kein Fehler aufgetreten." . PHP_EOL;
}

fclose($stderrStream);
fclose($channel);

Fehler auf dem Remote-System: PHP Fatal error: Testfehler in Command line code on line 1

// Wichtig · Fallstricke

Reihenfolge beachten: ssh2_fetch_stream() sollte direkt nach ssh2_exec() aufgerufen werden, bevor der stdout-Stream ausgelesen wird. Andernfalls kann es zu Blockierungen kommen, wenn der stderr-Puffer voll läuft.

Blockierender Modus: Ohne stream_set_blocking($stream, true) können die Streams unvollständige Daten liefern. Es empfiehlt sich, beide Streams (stdout und stderr) vor dem Lesen in den blockierenden Modus zu setzen.

PECL-Abhängigkeit: Die Funktion gehört zur PECL-Erweiterung ssh2 und ist nicht Teil der PHP-Kerninstallation. Eine Installation via pecl install ssh2 ist erforderlich.

Siehe auch

ssh2_exec ssh2_connect ssh2_auth_password stream_get_contents stream_set_blocking