Stdio React Laravel Package

Getting Started

Start by installing via Composer: composer require clue/stdio-react. This package provides an InputStream and OutputStream that work asynchronously with ReactPHP’s event loop — ideal for building interactive CLI tools (e.g., REPLs, chat clients, progress bars, or TUIs). The first step is to bind input/output to the current process:

$loop = React\EventLoop\Factory::create();
$stdin = new Clue\React\Stdio\InputStream(STDIN, $loop);
$stdout = new Clue\React\Stdio\OutputStream(STDOUT, $loop);

$stdin->on('data', function ($chunk) use ($stdout) {
    $stdout->write('You typed: ' . $chunk);
});
$loop->run();

Use the Terminal helper for advanced features like line editing and history (e.g., Terminal::createAutoDetect($loop)). Check the README’s "Examples" directory for minimal working demos (e.g., examples/readline.php).

Implementation Patterns

• Interactive Prompts: Combine InputStream with Terminal to build confirmation prompts (do you want to continue? (y/N)) with input validation and masking.
• Real-time Progress Bars: Use OutputStream to stream ANSI-aware updates (e.g., Writing [=====> ] 50%) without overwriting previous output.
• Command-Line Servers: Integrate with ReactPHP’s Server component — handle client connections over TCP while allowing operator commands via stdin (e.g., reload config, toggle debug mode).
• Pipe Support: Works seamlessly with proc_open() or streams — e.g., relay output from a subprocess to the terminal while accepting user input for interactive filtering.
• Multiline Editing: Leverage Terminal::enableRawMode() for full control over keystrokes (e.g., arrow keys, Ctrl+L for clear), enabling custom line editors.

Gotchas and Tips

• Raw Mode Cleanup: Always call $terminal->disableRawMode() (or use finally blocks) before exit — otherwise, the terminal may remain in broken state after crashes.
• Windows Compatibility: Raw mode and advanced ANSI features (like color) require modern Windows 10+ or clue/terminal-react’s ANSI emulation. Test on target platforms.
• Chunk Boundaries: Input events may emit partial UTF-8 characters — use $terminal->enableUtf8() to ensure reliable multi-byte handling (e.g., emojis, accented chars).
• Buffering Gotchas: OutputStream is non-blocking and may drop data if the underlying stream can’t keep up — always listen for error events or check $stdout->isWritable().
• Extensibility: Extend InputStream/OutputStream to add custom filters (e.g., logging all input to a file) or wrap with StreamDecorator for advanced transformations.
• Debugging Tip: Use php -d output_buffering=0 when testing — PHP’s output buffering can interfere with immediate terminal updates.