[RFC / Proposal] Built-in Native Terminal Primitives for TypePHP Standalone CLI Applications

[prateekbhujel]

Summary

TypePHP is a massive step forward for the PHP ecosystem, enabling ahead-of-time (AOT) compilation into standalone native executables (--mode=bin). Standalone binaries are particularly compelling for command-line tools, utilities, background workers, and system daemons.

However, modern CLI applications (interactive prompts, menus, password prompts, spinners, TUIs, terminal dimensions) fundamentally depend on low-level terminal primitives:

1. Raw Mode: Non-blocking character-by-character input without waiting for Enter.
2. Key Event Handling: Parsing arrow keys, function keys, Escape, Alt/Ctrl combinations cleanly.
3. Secret / Password Input: Masked or silent keyboard input without echoing passwords to the console.
4. Terminal Dimensions: Cross-platform retrieval of terminal columns and rows (getSize()).
5. Color & VT Support: Detecting truecolor, 256-color, VT100 support, and strictly honoring NO_COLOR.

Currently in standard PHP, CLI tools (such as Laravel Prompts or Symfony Console) resort to workarounds like shelling out to stty on POSIX or mode CON on Windows, or bundling external helper executables to read masked passwords. In a standalone AOT-compiled binary, spawning shell sub-processes breaks single-binary isolation, impacts startup latency, and fails in restricted environments.

---

Potential Solution: Dependency-Free Native Terminal Primitives

We have built and tested a pure, dependency-free C extension for terminal primitives (php-terminal):

• Zero external dependencies: Uses only POSIX libc / termios on Linux & macOS, and the Win32 Console API on Windows.
• True cross-platform parity: Equivalent behavior across Linux, macOS, and Windows without requiring WSL or third-party libraries like ncurses.
• Clean PHP stub declarations: Already defined via standard stub definitions (terminal.stub.php).

---

Discussion & Questions for the Maintainers

We would love to get feedback from @rango and the community on how this could best fit into TypePHP:

1. First-Party Module vs External Package:
   • Would you be open to having native terminal primitives bundled directly into TypePHP's runtime for standalone binaries (mode: bin), or do you prefer keeping it as an optional TypePHP-compatible package / example in examples/?
2. CLI Compiler Enhancement:
   • Could tpc itself benefit from native terminal detection (e.g. dynamic responsive progress bars matching terminal width via getSize(), or interactive project wizards)?
3. API & Namespace:
   • If integrated as a built-in runtime module, what namespace convention would be preferred (Terminal\ or TypePhp\Terminal\)?

I am eager to contribute a PR with an implementation and examples if this direction aligns with TypePHP's roadmap!