Signatur
Beschreibung
passthru() ähnelt den Funktionen exec() und system(), hat aber einen entscheidenden Unterschied: Die Ausgabe des externen Programms wird ungefiltert und binärsicher direkt an den aufrufenden Prozess (Browser oder Shell) durchgereicht. Das macht passthru() besonders geeignet, wenn das externe Programm Binärdaten produziert – etwa Bilder, komprimierte Archive oder andere binäre Ausgaben, die durch PHP nicht verändert werden dürfen.
Der optionale zweite Parameter $result_code wird nach der Ausführung mit dem Exit-Status des Programms gefüllt (0 bedeutet üblicherweise Erfolg). Damit lässt sich prüfen, ob das externe Programm fehlerfrei abgeschlossen hat.
Im Gegensatz zu exec(), das die Ausgabe in einem Array sammelt, und system(), das die Ausgabe als String puffert, leitet passthru() die Ausgabe sofort weiter, ohne sie intern zu speichern. Das spart Speicher bei großen Ausgaben und ermöglicht Streaming.
Sicherheitshinweis: Benutzereingaben dürfen niemals unbereinigt an passthru() übergeben werden. Immer escapeshellcmd() und/oder escapeshellarg() verwenden, um Command-Injection-Angriffe zu verhindern.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $command Pflicht | string | Der auszuführende Shell-Befehl als Zeichenkette. Benutzereingaben müssen zuvor mit escapeshellarg() oder escapeshellcmd() gesichert werden. |
|
| $result_code | int | null | Wird nach der Ausführung mit dem Exit-Status des Programms belegt. Ein Wert von 0 steht in der Regel für eine erfolgreiche Ausführung. |
Rückgabewert
passthru() hat keinen Rückgabewert. Die Ausgabe des Programms wird direkt an die Standardausgabe weitergeleitet.Beispiele
Binäres PNG-Bild mit ImageMagick erzeugen und direkt ausgeben
<?php
// Sicheres Übergeben eines Dateinamens aus Benutzereingabe
$filename = $_GET['file'] ?? 'photo.jpg';
$safeFilename = escapeshellarg('/var/images/' . basename($filename));
header('Content-Type: image/png');
// ImageMagick konvertiert das Bild und gibt es als PNG-Binärstrom aus
passthru('convert ' . $safeFilename . ' -resize 800x600 png:-', $exitCode);
if ($exitCode !== 0) {
// Fehlerbehandlung
error_log('ImageMagick-Fehler, Exit-Code: ' . $exitCode);
}Exit-Status eines Systembefehls überprüfen
<?php
// Prüfen, ob ein Verzeichnis existiert und dessen Inhalt auflisten
$dir = escapeshellarg('/var/www/html/uploads');
passthru('ls -lh ' . $dir, $exitCode);
if ($exitCode === 0) {
echo PHP_EOL . 'Verzeichnis erfolgreich aufgelistet.';
} else {
echo 'Fehler beim Auflisten. Exit-Code: ' . $exitCode;
}// Wichtig · Fallstricke
Sicherheit – Command Injection: Werden Benutzereingaben ungeprüft in den Befehl eingebaut, können Angreifer beliebige Shell-Befehle ausführen. Immer escapeshellarg() für einzelne Argumente und escapeshellcmd() für den gesamten Befehl verwenden.
safe_mode / disable_functions: In älteren PHP-Versionen (vor 5.4) konnte safe_mode die Ausführung einschränken. In modernen Umgebungen kann passthru über disable_functions in der php.ini deaktiviert sein – was in Shared-Hosting-Umgebungen häufig der Fall ist.
Output Buffering: Wenn Output Buffering aktiv ist (z. B. durch ob_start()), wird die Ausgabe gepuffert und nicht sofort gestreamt. Für echtes Streaming muss der Puffer vorher geleert werden (ob_end_flush()).
Windows-Kompatibilität: Auf Windows-Systemen unterscheidet sich das Shell-Verhalten (cmd.exe statt bash). Befehle und Escaping müssen ggf. angepasst werden.