PHP 8.7 Native Terminal API: Build Interactive CLI Without Hacks

Pain Points of Writing Interactive CLI in PHP

Developers using Symfony Console, Laravel Prompts, or custom PHP CLI tools have long struggled with basic terminal interactions:

Password input requires disabling echo (no plaintext display).

Arrow-key menus need individual keystroke capture (↑/↓/Enter) without waiting for Enter.

Adaptive table widths demand current terminal rows and columns.

Until now, PHP lacked any native cross-platform API for these tasks. Existing open-source packages rely on "black magic":

Linux/macOS : Frequent proc_open() calls to run stty -echo, stty raw, or stty size. This incurs process overhead and risks leaving the terminal stuck in no-echo state if the script crashes.

Windows : No stty support; developers must call proprietary Win32 Console APIs, making cross-platform compatibility extremely fragile.

This situation made PHP clumsy for building smooth terminal user interfaces (TUIs) and modern command-line tools compared to Go or Rust.

PHP RFC: Io\Terminal — Four Core Capabilities

The Io\Terminal RFC targets PHP 8.7 and introduces a native, cross-platform, object-oriented terminal interaction foundation under the Io\Terminal namespace.

1. Native Terminal Size Retrieval (No Child Processes)

Previously, getting terminal width was slow and error-prone. The new API uses a single native system call:

use Io\Terminal\Terminal;

$terminal = Terminal::fromStdio();
$size = $terminal->getSize();
if ($size !== false) {
    echo "当前终端：{$size->cols} 列 × {$size->rows} 行
";
}

2. Safe Raw Mode Lease Mechanism (Prevents Broken Terminals)

Interactive apps need raw mode, but a crash could leave the terminal unrestored. The RFC designs an elegant ModeToken (mode lease) mechanism:

Multiple components can request raw mode simultaneously; reference counting is used internally.

When the last token is released, or the PHP request ends normally, the underlying layer guarantees automatic restoration of the terminal to its initial state .

$mode = $terminal->enableRawMode();
try {
    // Handle interaction logic...
} finally {
    // Explicit restore; even if forgotten, object destruction or script exit will auto-revert
    $terminal->restoreMode($mode);
}

3. Single-Key Capture with Enum Support (Building Interactive Menus)

The readKey() method reads a single keystroke within a millisecond timeout and maps function keys to strongly typed Io\Terminal\Key enums:

use Io\Terminal\Key;
use Time\Duration;

// Wait for user keypress (max 3 seconds)
$key = $terminal->readKey(Duration::fromSeconds(3));

match ($key) {
    Key::Up => $menu->selectPrevious(),
    Key::Down => $menu->selectNext(),
    Key::Enter => $menu->confirm(),
    Key::Escape => $menu->exit(),
    Key::Resize => $menu->redraw($terminal->getSize()), // Even supports window resize events!
    default => echo "输入了字符: {$key}
",
};

4. Secure No-Echo Password Input

No more manually disabling and re-enabling echo:

echo "请输入数据库连接密码：";
$password = $terminal->readSecret();

During input, Backspace allows editing; Enter confirms; Ctrl+C, Ctrl+D, or Esc safely abort and throw an exception, removing the need for developers to handle edge cases manually.

Modernization of the Underlying Architecture

The RFC reveals a notable shift in modern PHP standard library design philosophy:

Systematic Namespacing : New functionality resides under Io\ (Input/Output) and companion Time\ namespaces, moving away from the scattered global functions of the past decade (e.g., posix_*, stream_*).

Object-Oriented & Strong Typing : Fully embraces readonly class, strong-typed enums ( enum Key), and exception-driven design ( TerminalException), aligning with modern static analysis standards.

Only Low-Level Foundations : The RFC explicitly states it provides only low-level native capabilities , not fancy UI rendering. Higher-level coloring, layout components remain the domain of community frameworks like Laravel Prompts, Symfony Console, and PHP-TUI.

Closing Thoughts

PHP was once mocked as "only good for web requests, can't do system-level tools." But with the rise of long-running frameworks (Workerman, RoadRunner, Swoole), static binary packaging (FrankenPHP, Micro), and polished CLI libraries, PHP's presence in microservices, ops tools, and command-line applications is growing. Io\Terminal may be a small low-level API proposal, but it fills a critical gap in PHP's journey toward a "modern general-purpose language."