stream_isatty — Funktion · PHP-Referenz

Signatur

stream_isatty(resource $stream): bool

Beschreibung

stream_isatty() gibt true zurück, wenn der übergebene Stream mit einem TTY (Teletypewriter) – also einem interaktiven Terminal – verbunden ist. Das ist zum Beispiel dann der Fall, wenn ein PHP-Skript direkt in einer Shell ausgeführt wird und STDOUT oder STDERR nicht in eine Datei oder Pipe umgeleitet wurden.

Die Funktion ist besonders nützlich, um in CLI-Skripten zu erkennen, ob die Ausgabe an ein echtes Terminal geht oder in eine Datei bzw. eine Pipe weitergeleitet wird. So können CLI-Tools beispielsweise ANSI-Farbcodes nur dann ausgeben, wenn tatsächlich ein Terminal vorhanden ist, das diese Sequenzen verarbeiten kann.

Typische Einsatzszenarien sind Fortschrittsbalken, farbige Konsolenausgaben oder interaktive Eingabeaufforderungen, die nur bei einer echten Terminalverbindung Sinn ergeben. Wird stdout hingegen in eine Datei geleitet (php script.php > output.txt), liefert die Funktion false.

Die Funktion ist das PHP-Äquivalent zu isatty() aus der C-Standardbibliothek und funktioniert plattformübergreifend auf Linux, macOS und Windows.

Parameter

Name	Typ	Default	Beschreibung
$stream Pflicht	resource		Ein geöffneter Stream-Ressource-Handle, z. B. `STDIN`, `STDOUT` oder `STDERR`, oder ein anderer mit `fopen()` geöffneter Stream.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn der Stream mit einem interaktiven Terminal (TTY) verbunden ist, andernfalls false. Gibt ebenfalls false zurück, wenn der übergebene Parameter kein gültiger Stream ist.

Beispiele

ANSI-Farben nur bei TTY-Ausgabe verwenden

<?php
// Gibt farbigen Text nur aus, wenn STDOUT ein echtes Terminal ist
if (stream_isatty(STDOUT)) {
    echo "\033[32mErfolgreich!\033[0m\n"; // Grüner Text im Terminal
} else {
    echo "Erfolgreich!\n"; // Keine ANSI-Codes in Dateien/Pipes
}

Erfolgreich! (grün formatiert, falls im Terminal)

Prüfung aller Standard-Streams

<?php
$streams = [
    'STDIN'  => STDIN,
    'STDOUT' => STDOUT,
    'STDERR' => STDERR,
];

foreach ($streams as $name => $stream) {
    $isTty = stream_isatty($stream);
    echo $name . ': ' . ($isTty ? 'TTY' : 'kein TTY') . PHP_EOL;
}
// Ausführung: php script.php
// STDIN:  TTY
// STDOUT: TTY
// STDERR: TTY

// Ausführung: php script.php > output.txt
// STDIN:  TTY
// STDOUT: kein TTY
// STDERR: TTY

STDIN: TTY STDOUT: TTY STDERR: TTY

Interaktive Eingabe nur im Terminal anfordern

<?php
if (stream_isatty(STDIN)) {
    echo 'Bitte Namen eingeben: ';
    $name = trim(fgets(STDIN));
    echo 'Hallo, ' . htmlspecialchars($name) . '!' . PHP_EOL;
} else {
    // Nicht-interaktiver Modus: Eingabe aus Pipe oder Datei lesen
    $name = trim(fgets(STDIN));
    echo 'Verarbeite: ' . htmlspecialchars($name) . PHP_EOL;
}

Bitte Namen eingeben: (Eingabe durch Benutzer)

// Wichtig · Fallstricke

Verfügbarkeit: Die Funktion steht erst ab PHP 7.2.0 zur Verfügung. In älteren PHP-Versionen kann eine ähnliche Funktionalität über die POSIX-Erweiterung mit posix_isatty() erreicht werden, die jedoch nur auf Unix-artigen Systemen verfügbar ist.

Windows-Besonderheit: Auf Windows liefert stream_isatty() für die Standard-Streams korrekte Ergebnisse, auch in Umgebungen wie PowerShell oder dem Windows Terminal. Das Verhalten kann sich jedoch bei Pipe-Weiterleitungen und bestimmten Terminal-Emulatoren unterscheiden.

Sicherheitshinweis: Vertraue der Rückgabe dieser Funktion nicht für sicherheitskritische Entscheidungen, da sie ausschließlich für UX-Zwecke (z. B. Farbausgabe) gedacht ist.

Siehe auch

posix_isatty stream_get_meta_data fopen defined