Term React Laravel Package

Getting Started

Start by installing via Composer: composer require clue/term-react. This package provides a streaming ANSI terminal emulator for ReactPHP, ideal for building interactive CLI tools, remote shell proxies, or TTY-aware WebSocket servers. Your first use case is likely capturing and processing terminal input/output in async PHP — for example, acting as a middleware layer between a WebSocket client and an underlying process. Initialize the emulator with a sink (e.g., a WriteStream) to receive emitted ANSI sequences:

use Clue\React\Term\Term;
use React\Stream\ThroughStream;

$sink = new ThroughStream();
$term = new Term($sink);

// Hook up input stream (e.g., stdin or socket)
$stdin->on('data', [$term, 'input']);
// Pipe output back
$sink->pipe($stdoutOrSocket);

Check the examples/ folder in the repo for minimal working demos like echo-server.php or websocket-term.php.

Implementation Patterns

Common patterns involve embedding Term in event-driven CLI or server apps:

• Process proxying: Use Term to forward interactive shells to subprocesses (React\ChildProcess\Process) and handle PTY-like interactions.
• WebSocket to TTY: Serve a terminal over WebSockets (e.g., Ratchet\WebSocket\WsServer), converting WS messages ↔ terminal escape sequences.
• ANSI parsing & reformatting: Intercept the $sink stream to sanitize or augment output (e.g., log terminal sessions, convert colors).
• Input filtering: Override Term::input() via extension or composition to inject hotkeys or command shortcuts before forwarding to the sink.

For scalable use, couple with React\EventLoop\Loop and a PSR-7/PSR-15-compatible HTTP/WebSocket stack (e.g., React\Http + React\Socket). Always ensure you handle backpressure by enabling流控 (setEncoding('binary'), respecting isWritable()).

Gotchas and Tips

• Backpressure matters: The $sink must be able to consume data quickly. If downstream (e.g., WebSocket) is slow, pipe via ThroughStream + Buffer to avoid memory bloat.
• Terminal state loss: Term is stateless-by-default. If reconnecting clients (e.g., SSH over WS), you must implement your own state snapshot (e.g., save buffer + cursor state via $term->exportState() — note: this method doesn’t exist in current v1; you must subclass and track manually).
• ANSI quirks: Some sequences (e.g., cursor movement, color reset) are context-sensitive. Test with script or asciinema to verify behavior.
• Extending functionality: The class is final and non-extendable — override behavior by composition: wrap Term and delegate calls, intercepting input() and sink events.
• Async process sync: When wrapping subprocesses, ensure PID cleanup via exit event handlers to avoid zombie processes — Term doesn’t manage child lifecycle.
• Debugging: Enable logging by piping the sink to a ResourceStream writing to php://stderr, or use a custom sink that logs data events with timestamps.