[PHP-DEV] Re: [PHP DEV] [Discussion] Native terminal helpers for PHP CLI

Mailing Lists php.internals
1

Hi Tim, hi internals,

Thank you for the detailed feedback. Your observations on namespace grouping, instance handles, unbacked enums, and standard library conventions made complete sense.

Instead of just replying in theory, I took the time over the past couple of days to step back, study how other ecosystems handle terminal interfaces, and rebuild the extension accordingly. Version 0.8.0 is now released with that exact architecture.

To answer your question regarding the domain problem:

The primary issue is that PHP CLI currently lacks native primitives for non-canonical raw terminal mode and single keypress reading. Modern interactive CLI tools in userland (such as Laravel Prompts, Symfony Console, and interactive tools) want to deliver rich experiences like searchable selection menus, autocomplete, multi-choice checkboxes, spinners, and hidden password prompts.

Today, userland libraries face two severe problems:

  1. On Linux and macOS, packages work around the missing primitives by executing the external stty tool using proc_open or exec. However, inside minimal Docker containers (such as Alpine or slim environments where stty is absent) or environments where process execution functions are restricted, interactive CLI tools fail completely.

  2. On Windows, stty does not exist. Windows uses the Win32 Console API. Because PHP has lacked these primitives, interactive CLI packages on Windows either crash or fall back to crude text prompts where the user must type choices manually and hit Enter. Reading password input without displaying characters on Windows even required distributing separate helper executables.

  3. When a script exits unexpectedly or an unhandled exception occurs while the terminal is in raw mode, the user shell is left corrupted with disabled echo and hidden cursor.

Looking at how other languages tackle this:

  • Rust (termion and crossterm): Rust relies on RAII guards where entering raw mode returns a handle whose destructor automatically restores canonical cooked mode on drop or panic.
  • Go (golang.org/x/term): Provides low-level primitives in the extended standard library (MakeRaw, Restore, GetSize, ReadPassword) on top of which tools like Bubbletea are built.
  • Node.js: Integrates raw mode toggling and size queries directly onto TTY streams via libuv.
  • Python: Provides termios on POSIX and msvcrt on Windows in the standard library to guarantee cross-platform terminal parity.

Following your guidance, version 0.8.0 adopts the following design:

  1. Namespace grouping:
    All symbols are placed under the Io\Terminal namespace, avoiding top-level name reservation and aligning with modern asynchronous and stream polling conventions.

  2. Instance-based Terminal handle:
    Classes are no longer static wrappers. The Io\Terminal\Terminal class encapsulates a stream descriptor, created via named constructors stdin(), stdout(), stderr(), or by wrapping custom stream resources.

  3. Automatic RAII cleanup:
    Both Terminal instances and ModeToken objects track active raw mode and automatically restore terminal state upon destruction. If an uncaught exception terminates script execution, the destructor restores canonical mode so the developer shell is never left broken.

  4. Unbacked enums:
    Backend, Stream, ColorDepth, and Key are now unbacked enums matching core standards. Methods such as bits() on ColorDepth supply numerical details without scalar backing.

  5. Free-standing procedural functions:
    Io\Terminal provides procedural functions like is_tty(), read_key(), and get_size() for functional script usage.

  6. Compatibility:
    The legacy Terminal facade and class aliases remain in place so existing userland code continues to work smoothly.

The complete codebase, 49 tests, and the continuous integration matrix covering Unix and Windows across PHP versions 8.1 through 8.5 are live on GitHub and installable via PIE (package prateekbhujel/php-terminal).

The GitHub repository is here:
https://github.com/prateekbhujel/php-terminal

Release v0.8.0 with prebuilt Windows DLL assets:
https://github.com/prateekbhujel/php-terminal/releases/tag/v0.8.0

I would love to hear any further thoughts on whether this design aligns with what you would like to see for an RFC targeted at PHP 8.7.

Thanks,
Pratik

2

On Fri, Sep 18, 2026, at 04:19, Pratik Bhujel wrote:

Hi Tim, hi internals,

Thank you for the detailed feedback. Your observations on namespace grouping, instance handles, unbacked enums, and standard library conventions made complete sense.

Instead of just replying in theory, I took the time over the past couple of days to step back, study how other ecosystems handle terminal interfaces, and rebuild the extension accordingly. Version 0.8.0 is now released with that exact architecture.

To answer your question regarding the domain problem:

The primary issue is that PHP CLI currently lacks native primitives for non-canonical raw terminal mode and single keypress reading. Modern interactive CLI tools in userland (such as Laravel Prompts, Symfony Console, and interactive tools) want to deliver rich experiences like searchable selection menus, autocomplete, multi-choice checkboxes, spinners, and hidden password prompts.

Today, userland libraries face two severe problems:

  1. On Linux and macOS, packages work around the missing primitives by executing the external stty tool using proc_open or exec. However, inside minimal Docker containers (such as Alpine or slim environments where stty is absent) or environments where process execution functions are restricted, interactive CLI tools fail completely.

  2. On Windows, stty does not exist. Windows uses the Win32 Console API. Because PHP has lacked these primitives, interactive CLI packages on Windows either crash or fall back to crude text prompts where the user must type choices manually and hit Enter. Reading password input without displaying characters on Windows even required distributing separate helper executables.

  3. When a script exits unexpectedly or an unhandled exception occurs while the terminal is in raw mode, the user shell is left corrupted with disabled echo and hidden cursor.

Looking at how other languages tackle this:

  • Rust (termion and crossterm): Rust relies on RAII guards where entering raw mode returns a handle whose destructor automatically restores canonical cooked mode on drop or panic.
  • Go (golang.org/x/term): Provides low-level primitives in the extended standard library (MakeRaw, Restore, GetSize, ReadPassword) on top of which tools like Bubbletea are built.
  • Node.js: Integrates raw mode toggling and size queries directly onto TTY streams via libuv.
  • Python: Provides termios on POSIX and msvcrt on Windows in the standard library to guarantee cross-platform terminal parity.

Following your guidance, version 0.8.0 adopts the following design:

  1. Namespace grouping:
    All symbols are placed under the Io\Terminal namespace, avoiding top-level name reservation and aligning with modern asynchronous and stream polling conventions.

  2. Instance-based Terminal handle:
    Classes are no longer static wrappers. The Io\Terminal\Terminal class encapsulates a stream descriptor, created via named constructors stdin(), stdout(), stderr(), or by wrapping custom stream resources.

  3. Automatic RAII cleanup:
    Both Terminal instances and ModeToken objects track active raw mode and automatically restore terminal state upon destruction. If an uncaught exception terminates script execution, the destructor restores canonical mode so the developer shell is never left broken.

  4. Unbacked enums:
    Backend, Stream, ColorDepth, and Key are now unbacked enums matching core standards. Methods such as bits() on ColorDepth supply numerical details without scalar backing.

  5. Free-standing procedural functions:
    Io\Terminal provides procedural functions like is_tty(), read_key(), and get_size() for functional script usage.

  6. Compatibility:
    The legacy Terminal facade and class aliases remain in place so existing userland code continues to work smoothly.

The complete codebase, 49 tests, and the continuous integration matrix covering Unix and Windows across PHP versions 8.1 through 8.5 are live on GitHub and installable via PIE (package prateekbhujel/php-terminal).

The GitHub repository is here:
https://github.com/prateekbhujel/php-terminal

Release v0.8.0 with prebuilt Windows DLL assets:
https://github.com/prateekbhujel/php-terminal/releases/tag/v0.8.0

I would love to hear any further thoughts on whether this design aligns with what you would like to see for an RFC targeted at PHP 8.7.

Thanks,
Pratik

Meta question: can you please use your email’s “reply” feature instead of writing a new email with the same subject each time. That allows people to follow the thread.

— Rob

3

Hi

it seems your replies don't contain proper `in-reply-to` or `references` headers, which breaks the threading. As an example in the archives at php.internals: Re: [PHP DEV] [Discussion] Native terminal helpers for PHP CLI no other emails from the discussion are shown and php.internals: Re: Re: [PHP DEV] [Discussion] Native terminal helpers for PHP CLI only shows your email and my reply. On externals.io new threads are created for every email. Can you check the configuration of your email client and make sure to always use real “Reply” instead of sending a fresh email?

On 2026-09-18 04:19, Pratik Bhujel wrote:

To answer your question regarding the domain problem:

The primary issue is that PHP CLI currently lacks native primitives for
non-canonical raw terminal mode and single keypress reading. Modern
interactive CLI tools in userland (such as Laravel Prompts, Symfony
Console, and interactive tools) want to deliver rich experiences like
searchable selection menus, autocomplete, multi-choice checkboxes,
spinners, and hidden password prompts.

Yes, I roughly understand the problem that is being solved. It's just something I never had to deal with, so I can't comment on whether the solution is complete and ergonomic.

2. Instance-based Terminal handle:
Classes are no longer static wrappers. The Io\Terminal\Terminal class
encapsulates a stream descriptor, created via named constructors stdin(),
stdout(), stderr(), or by wrapping custom stream resources.

For consistency with the recently introduced APIs, the named constructors should start with a prefix that clearly indicates that the method is a constructor. As of now we have the following:

- Dom\HTMLDocument::createEmpty(), ::createFromFile(), ::createFromString()
- Time\Duration::fromSeconds(), ::fromMilliseconds(), …, ::fromIso8601DurationString()
- Uri\Rfc3986\Uri::parse() (though this one also has a real constructor).

For the Terminal I wonder why we need to have stdin, stdout, and stderr separately. For me logically a “Terminal” is a combination of all three and I would expect them to be “synchronized” if that makes sense?

3. Automatic RAII cleanup:
Both Terminal instances and ModeToken objects track active raw mode and
automatically restore terminal state upon destruction. If an uncaught
exception terminates script execution, the destructor restores canonical
mode so the developer shell is never left broken.

That makes sense to me.

5. Free-standing procedural functions:
Io\Terminal provides procedural functions like is_tty(), read_key(), and
get_size() for functional script usage.

I've taken another look at these and have some point that stood out to me:

- Do we need all three of get_size(), get_width(), get_height()? The latter two seem redundant.
- Should related methods have a common prefix for discoverability? So mode_enable_raw() and mode_restore() instead of enable_raw_mode() and restore_mode()?
- Many (all?) of the functions also exists as methods on the Terminal class. This redundant procedural + object-oriented API design is something we no longer do. Decide on one of the two, depending on what is more useful. I expect the OO variant to be the right choice due to the RAII support.

Best regards
Tim Düsterhus

4

Hi Rob, hi Tim,

@Rob: Thanks for pointing that out! My bad on the broken threads earlier. I was sending from a separate setup that stripped the reference headers. Replying directly via Reply-All now so this stays in the same thread on both the archives and Discourse.

@Tim: Thanks a lot for this feedback, it makes total sense.

  1. Unifying the streams:
    You’re completely right about stdin/stdout/stderr. Under the hood, the terminal is a single interactive TTY session anyway. Managing them as separate handles just invites state desync and conflicting destructors. I’ll consolidate this into a single handle representing the terminal session. e.g. Terminal::open() / Terminal::create(), plus maybe Terminal::fromStreams() if someone needs custom redirection or testing.

  2. Named constructors:
    Got it. I’ll switch to the create*() / from*() prefixes to align with modern core APIs like Dom\HTMLDocument and Time\Duration instead of bare names.

  3. OO-only vs procedural:
    I completely agree. The procedural duplication was carried over from older habits, but since RAII cleanup via the destructor is the entire safety backbone of this extension, an OO-only API (Io\Terminal\Terminal) is much cleaner and avoids unnecessary duplication. I’ll drop the procedural functions.

  4. Redundant getters & discoverability:
    Dropping getWidth() / getHeight() in favor of just $terminal->getSize() returning a small size object/tuple makes the interface a lot leaner. I’ll also make sure the mode methods have clear, grouped naming.

I’ll start working on these refactors in the codebase and update the RFC draft accordingly.

Thanks again for steering this in the right direction!

Best,
Pratik