Add Io\Terminal native terminal primitives by prateekbhujel · Pull Request #23941 · php/php-src

prateekbhujel · 2026-09-27T00:16:00Z

Implementation of the proposed PHP 8.7 Io\Terminal RFC, with the API proposed for version 0.3:

https://wiki.php.net/rfc/io_terminal

This adds native terminal primitives to ext/standard, alongside Io\Poll, using POSIX terminal APIs and the Windows Console API.

The API provides:

Terminal and ModeToken interfaces for userland implementations and test doubles.
One native SystemTerminal implementation, created through fromStdio() or fromStreams($input, $output = null).
TerminalSize, a directly constructible readonly value object, and getSize(): ?TerminalSize, without COLUMNS/LINES fallbacks.
Shared raw-mode leases through enableRawMode(): SystemModeToken and restoreMode(?ModeToken $mode = null): bool.
readKey(?Time\Duration $timeout = null, ?Time\Duration $sequenceTimeout = null): Key|string|null.
readLine(): ?string.
readSecret(?Time\Duration $timeout = null): ?string.
TerminalException for operational failures.

Raw-mode ownership is coordinated per logical terminal within a PHP request. Leases can be released in any order, including through another wrapper for the same terminal; the final release restores the saved mode using an independent native descriptor or handle. Native restoration rejects foreign, consumed, or unrelated tokens. A no-argument restoreMode() returns false when the wrapper has no active retained token.

readKey() and readSecret() manage their own temporary terminal mode. Explicit raw-mode leases support longer interactive sessions.

readLine() has no timeout or line-editor features. It preserves spaces and tabs, removes LF/CRLF terminators, returns null on immediate EOF, and returns a final unterminated line at EOF. POSIX terminal reads use the existing line discipline and wait for readability after EAGAIN/EWOULDBLOCK without changing descriptor flags. Windows console reads use native line input and restore the previous console mode. Redirected PHP streams retain their buffering, blocking, and read-timeout behavior. Line reads reject an active managed raw-mode lease for the same logical terminal, even through another wrapper.

Key and secret reads return null on timeout; key-input EOF and secret cancellation throw TerminalException. On POSIX, incomplete UTF-8 bytes are retained across key-read timeouts and prepended when line reading continues. Escape ambiguity is separate: a standalone Escape becomes Key::Escape, while a consumed incomplete escape sequence may be returned as a prefix string.

PHPT coverage in ext/standard/tests/terminal/ includes contracts and test doubles, redirected and buffered streams, key decoding, timeouts, secret input, resize handling, and POSIX PTY cases for shared leases, token lifetime, cross-wrapper restoration, unrelated terminals, EOF, and nonblocking line input. The Windows-specific line-input test exercises redirected streams; native ReadConsoleW() validation remains needed.

The implementation remains under review. Platform CI results are tracked on this pull request.

Reference extension and prior ecosystem work:

https://github.com/prateekbhujel/php-terminal

TimWolla · 2026-09-27T14:11:24Z

+// Key identity and comparison
+var_dump(Key::Up === Key::Up);
+var_dump(Key::Up !== Key::Down);


This is just testing that enums work. Overall this test doesn't seem to be particularly useful.

TimWolla · 2026-09-27T14:30:25Z

 static zend_class_entry *php_io_poll_watcher_class_entry;
 static zend_class_entry *php_io_poll_handle_class_entry;
-static zend_class_entry *php_io_exception_class_entry;
+PHPAPI zend_class_entry *php_io_exception_class_entry;


This would should be moved out of io_poll.c as a separate PR.

TimWolla · 2026-09-27T14:34:30Z

+	HANDLE handle = input;
+	DWORD mode;
+	WCHAR high_surrogate = 0;
+	DWORD raw_mode;
+	smart_str secret = {0};
+	bool success = false;
+	bool failed = false;
+	bool mode_changed = false;


Reduce the scope of variables as much as possible.

TimWolla · 2026-09-27T16:14:47Z

+
+// Zero duration poll
+$res = $t->readKey(Duration::fromSeconds(0));
+var_dump($res === false || is_string($res) || is_object($res));


Is this not just testing the return type is correct? Make this expectation stronger (or remove it).

TimWolla · 2026-09-27T16:15:27Z

+
+// Named constructors
+$t1 = Terminal::create();
+var_dump($t1 instanceof Terminal);


Suggested change

var_dump($t1 instanceof Terminal);

var_dump($t1);

- Coordinate POSIX raw mode token ownership by underlying terminal device identity (tty_dev) so overlapping sessions and multiple descriptors reliably restore canonical mode. - Forward SIGWINCH to existing signal handlers and track terminal dimensions on Terminal instances to detect between-read resizes. - Allow zero-duration readKey() to return immediately without waiting for sequence timeout. Clamp finite timeouts and guard time_t conversions. - Validate continuation bytes during UTF-8 secret reading and dispatch non-continuation control bytes to preserve Ctrl+C cancellation. - Preserve high surrogate across repeated Windows console input events. - Replace synthetic non-TTY test fallbacks with genuine PTY tests and add regression tests for non-TTY streams, timeouts, secret controls, and resizes.

nicolas-grekas · 2026-09-28T12:59:54Z

+	memcpy(saved->magic, PHP_IO_TERMINAL_MODE_TOKEN_MAGIC, PHP_IO_TERMINAL_MODE_TOKEN_MAGIC_LEN);
+	saved->stream = fd;
+	saved->mode = mode;
+	saved->tty_dev = st.st_rdev;


st_rdev isn't a reliable terminal identity: it's too strict for /dev/tty (5:0 vs 136:N for the same terminal) and too loose for pty masters (all 5:2, so two unrelated proc_open() ptys are considered the same terminal, and releasing the first token leaves the first pty in raw mode).

A portable way to get a stable identity:

tcgetsid(fd) == getsid(0) means fd is our controlling terminal, whatever path it was opened from (/dev/tty, /dev/pts/N, stdin) - a process has at most one;

otherwise, ptsname(fd) is non-NULL for a pty master (ptsname_r() for ZTS), and stat() on it gives the slave's st_rdev;

otherwise, st_rdev is reliable.

On Linux, ioctl(fd, TIOCGDEV) does all of this in one call (136:N for both /dev/tty and a pty master).

(same for the checks in php_io_terminal_mode_token_stream_is_valid())

Hi @nicolas-grekas , Thanks so much for the guidance! I've refactored raw mode to use your proposed shared-record refcounting model with an independent restore descriptor and the updated POSIX identity checks. Everything is now order-independent and survives closed streams and destroyed Terminal objects as suggested.

TimWolla

I'm only remarking the first occurrence of any given point. Please carefully check if the same suggestion would apply elsewhere for everything.

TimWolla · 2026-09-28T18:34:31Z

+		RETURN_THROWS();
+	}
+
+	zend_update_property_long(php_io_terminal_terminal_size_ce, Z_OBJ_P(ZEND_THIS), "cols", sizeof("cols") - 1, cols);


You need to check for exceptions after this call, the assigning will fail when calling the constructor on an already-constructed object and then trying to assign to rows will fail again and and throw another exception.

See ZEND_METHOD(Deprecated, __construct) for an example of how to make the check.

Added if (UNEXPECTED(EG(exception))) { RETURN_THROWS(); } after each readonly property assignment in TerminalSize::__construct(), matching Deprecated::__construct(). Re-invoking the constructor on an initialized instance now terminates immediately on the $cols modification error without attempting subsequent assignments.

TimWolla · 2026-09-28T18:34:59Z

+static void php_io_terminal_create_terminal_size(zval *return_value, zend_long cols, zend_long rows)
+{
+	object_init_ex(return_value, php_io_terminal_terminal_size_ce);
+	zend_update_property_long(php_io_terminal_terminal_size_ce, Z_OBJ_P(return_value), "cols", sizeof("cols") - 1, cols);
+	zend_update_property_long(php_io_terminal_terminal_size_ce, Z_OBJ_P(return_value), "rows", sizeof("rows") - 1, rows);
+}


Consider object_init_with_constructor() instead of a custom helper.

Removed the internal initialization helper; Terminal::getSize() now instantiates TerminalSize via object_init_with_constructor().

TimWolla · 2026-09-28T18:36:46Z

+	int fd = input;
+	struct termios mode;
+	struct termios raw_mode;
+	smart_str secret = {0};
+	bool success = false;
+	bool mode_changed;
+	php_poll_ctx *poll_ctx;


Narrowing the scope is possible for a number of variables here (probably also in other functions).

Narrowed variable declarations to their point of first use throughout io_terminal.c.

TimWolla · 2026-09-28T18:38:57Z

+#if SIZEOF_TIME_T < 8
+		if (timeout_duration->duration.seconds > PHP_IO_TERMINAL_TIME_T_MAX) {
+			timeout.tv_sec = PHP_IO_TERMINAL_TIME_T_MAX;
+		} else {
+			timeout.tv_sec = (time_t) timeout_duration->duration.seconds;
+		}
+#else
+		timeout.tv_sec = (time_t) timeout_duration->duration.seconds;


We don't have any other SIZEOF_TIME_T in the codebase, is this an issue that also affects the polling API? Should an exception being thrown for out-of-range Durations instead of silently clamping them?

Replaced #if SIZEOF_TIME_T < 8 with a static inline clamping helper using sizeof(time_t) < 8.

Regarding clamping vs throwing: php_poll.c / io_poll.c takes the same approach when a Duration overflows INT_MAX milliseconds, capping rather than throwing because a timeout exceeding the platform limit is practically indefinite. The clamping helper keeps that behavior consistent between the two I/O extensions.

TimWolla · 2026-09-28T18:39:52Z

+#if !defined(PHP_WIN32) && defined(SIGWINCH) && defined(ZTS)
+	php_io_terminal_resize_mutex = tsrm_mutex_alloc();
+#endif
+#if !defined(PHP_WIN32) && !defined(PHP_IO_TERMINAL_HAVE_PTSNAME_R) && defined(ZTS)
+	php_io_terminal_ptsname_mutex = tsrm_mutex_alloc();
+#endif


For readability it probably makes sense to poll the ZTS check to the beginning of the condition (or as a separate condition wrapping the internal conditions).

Grouped the ZTS checks into outer #ifdef ZTS blocks in MINIT/MSHUTDOWN and simplified the mutex lock/unlock helpers into clean macros.

- Check EG(exception) after readonly property assignment in TerminalSize::__construct - Instantiate TerminalSize with object_init_with_constructor in Terminal::getSize - Match POSIX/Windows terminal identities by unique device/handle, avoiding raw descriptor reuse - Verify actual terminal state after tcsetattr and GetConsoleMode - Protect readSecret against NULL deref on disconnect, abort on control/escape sequences, and preserve fragmented UTF-8 across boundaries - Account for timeouts with zend_hrtime monotonic deadline across escape and multibyte decoding - Narrow variable declarations and simplify ZTS mutex macro guards

…cret timeouts - Fix cancellation inside readSecret() escape parsing: - Abort on Ctrl+C, Ctrl+D, Escape, Enter inside CSI and SS3 sequences via terminal restoration path. - Distinguish cancellation, EOF, internal 25ms sequence timeout (which ends sequence skipping and continues secret input), and overall secret timeout. - Discard valid CSI (e.g. arrow keys) and SS3 (e.g. F1) sequences without exiting or emitting garbage. - Enforce one monotonic read deadline in readKey(): - Cap sequence timeout and UTF-8 continuation reads by remaining overall budget. - Zero timeout executes non-blocking read without blocking wait even if sequenceTimeout is specified. - Incomplete escape sequences return raw byte strings; incomplete UTF-8 sequences retain pending bytes across calls and return null on timeout. - Adopt null for absence: - Update Terminal::getSize() return type to ?TerminalSize. - Update Terminal::readKey() return type to Key|string|null. - Keep Terminal::restoreMode() return type as bool. - Add optional overall timeout to Terminal::readSecret(?Time\Duration $timeout = null): - Returns null on timeout, '' on empty submission (immediate Enter). - Throws TerminalException on cancellation/failure. - Throws ValueError on negative duration. - Introduce mockable boundaries: - Add Io\Terminal\TerminalInterface and Io\Terminal\ModeTokenInterface. - Make native Terminal implement TerminalInterface and ModeToken implement ModeTokenInterface while remaining final. - Have native restoreMode(?ModeTokenInterface $mode = null) validate native ModeToken, rejecting foreign tokens with ValueError. - Add comprehensive regression and acceptance tests.

DanielEScherzer

some initial thoughts

DanielEScherzer · 2026-09-29T04:32:01Z

+# define PATH_MAX 1024
+#endif
+
+static bool php_io_terminal_get_slave_dev_from_pty_master(int fd, dev_t *slave_dev)


please use more inclusive names in new code, i.e. avoid "slave" and "master"

Updated the new PTY identifiers to neutral terminology; the platform ptsname*() APIs remain unchanged.

DanielEScherzer · 2026-09-29T04:33:49Z

+	if (GetConsoleMode(shared->restore_stream, &actual_mode) && actual_mode != shared->saved_mode) {
+		return false;
+	}
+	return true;


both blocks end with return true, maybe move that out of the preprocessor conditional?

Done — moved the common return true outside the conditional.

DanielEScherzer · 2026-09-29T04:35:06Z

+
+	if (intern->valid && intern->shared != NULL) {
+		const char *err = NULL;
+		if (!php_io_terminal_release_token_lease(intern, &err)) {


this error isn't used for anything, so can just pass NULL

Updated — passing NULL directly since the error output isn't used here.

DanielEScherzer · 2026-09-29T04:37:25Z

+	WCHAR *pending_key_high_surrogate
+)
+{
+	DWORD records_read;


not needed for a while, suggest declaring lower down

Updated — the declaration now sits at first use.

DanielEScherzer · 2026-09-29T04:37:58Z

+	HANDLE handle = input;
+	DWORD mode = 0;
+	WCHAR high_surrogate = *pending_high_surrogate;
+	DWORD raw_mode;


some of these are not needed for a while, e.g. raw_mode can be declared as part of its initialization on 998

also applies in a number of other places, not going to point out each time

Narrowed raw_mode, key, and repeats to their points of initialization.

DanielEScherzer · 2026-09-29T04:38:14Z

+	}
+	mode_changed = raw_mode != mode;
+
+	for (;;) {


probably clearer to use

Suggested change

for (;;) {

while (true) {

Updated to while (true).

DanielEScherzer · 2026-09-29T04:40:44Z

+
+		pending->bytes[pending->length++] = key;
+		if ((key & 0xc0) != 0x80) {
+			zend_string *invalid = zend_string_init((const char *) pending->bytes, pending->length, false);


I think this is just the same result as a break here

Yep, this reaches the same common cleanup/return path. Simplified it to break.

DanielEScherzer · 2026-09-29T04:45:54Z

+#define PHP_IO_TERMINAL_CSI_IS(literal) \
+	(seq_len == sizeof(literal) - 1 && memcmp(seq, literal, sizeof(literal) - 1) == 0)
+
+		if (PHP_IO_TERMINAL_CSI_IS("\x1b[A")) return ZSTR_INIT_LITERAL("up", false);


a bunch of these have the same length in the comparison, and so this is going to have a whole bunch of unneeded comparisons of the seq_len vs the potential key. Maybe separate them out?

#define PHP_IO_TERMINAL_CSI_IS(literal) (memcmp(seq, literal, strlen(literal) == 0) if (seq_len == strlen("\x1b[B")) { if (PHP_IO_TERMINAL_CSI_IS("\x1b[B")) return ZSTR_INIT_LITERAL("down", false); if (PHP_IO_TERMINAL_CSI_IS("\x1b[C")) return ZSTR_INIT_LITERAL("right", false); if (PHP_IO_TERMINAL_CSI_IS("\x1b[D")) return ZSTR_INIT_LITERAL("left", false); // ... } else if (seq_len == strlen("\x1b[3~")) { if (PHP_IO_TERMINAL_CSI_IS("\x1b[3~")) return ZSTR_INIT_LITERAL("delete", false); if (PHP_IO_TERMINAL_CSI_IS("\x1b[5~")) return ZSTR_INIT_LITERAL("pageup", false); if (PHP_IO_TERMINAL_CSI_IS("\x1b[6~")) return ZSTR_INIT_LITERAL("pagedown", false); } else if (seq_len == strlen("\x1b[11~")) { if (PHP_IO_TERMINAL_CSI_IS("\x1b[11~")) return ZSTR_INIT_LITERAL("f1", false); if (PHP_IO_TERMINAL_CSI_IS("\x1b[12~")) return ZSTR_INIT_LITERAL("f2", false); if (PHP_IO_TERMINAL_CSI_IS("\x1b[13~")) return ZSTR_INIT_LITERAL("f3", false); // ... }

but then the memory comparison against \x1b[ is repeated a whole bunch, and this can be further optimized

not urgent since this still needs an RFC, just noting

Grouped the known sequences by length so we avoid repeating the length comparison for every candidate. The mappings and fallback behavior are unchanged.

DanielEScherzer · 2026-09-29T04:49:59Z

+ * @generate-c-enums
+ */
+
+namespace Io\Terminal {


you can just have a semicolon declaration and then don't need to indent everything

Changed the stub to the semicolon namespace form and regenerated arginfo.

I would recommend against this change: It adds unnecessary churn when later introducing sub-namespaces. For ext/date/time.stub.php I specifically started using the brace version right away.

Ah, I hadn’t considered the future sub-namespace case when I applied Daniel’s suggestion. I was looking at it as a straightforward cleanup for the current single namespace. The ext/date/time.stub.php precedent makes the reason for keeping the braces clear. I’ve switched it back and regenerated the generated headers.

NattyNarwhal · 2026-09-29T17:06:55Z

FWIW the timespec functions may be useful to extract into another utility file in the future. poll has php_poll_timespec_to_ms, if we use them in more places to deal with APIs like these.

Also, perhaps it might be useful to split the Unix/Windows backends into their own files, if it gets unwieldy.

prateekbhujel · 2026-09-30T04:32:09Z

Yeah, both make sense. I kept them local for now since the terminal implementation is still fairly self-contained, but if the timespec helpers start being reused elsewhere, pulling them into a shared utility would be cleaner.

Same for the platform code, if the Unix/Windows sides keep growing, splitting them out would probably make the implementation easier to maintain.

Thanks for pointing it out.

…d-line contract

prateekbhujel added 3 commits September 26, 2026 21:09

Add Io\Terminal native terminal primitives

b977622

Align terminal size behavior with RFC

bb4d1d6

Test native-only terminal size lookup

ef074a1

github-actions Bot added Category: Build System Extension: standard ABI break labels Sep 27, 2026

prateekbhujel changed the title ~~Rfc io terminal~~ Add Io\Terminal native terminal primitives Sep 27, 2026

prateekbhujel added 2 commits September 27, 2026 06:53

Update reflection test for Io Terminal classes

ca076e2

Fix terminal size test namespace

d0e9bb9

github-actions Bot added the Extension: reflection label Sep 27, 2026

prateekbhujel marked this pull request as ready for review September 27, 2026 02:49

prateekbhujel requested review from DanielEScherzer, bukka and kocsismate as code owners September 27, 2026 02:49

TimWolla added the Status: Requires RFC label Sep 27, 2026

TimWolla reviewed Sep 27, 2026

View reviewed changes

prateekbhujel added 7 commits September 27, 2026 19:09

Address Io Terminal core review

1e6a673

Harden terminal input and mode restoration

37be035

Test terminal escape sequence handling

1b666b5

Preserve stream validation errors

c684f55

Keep unsupported terminal sequences raw

e826bab

Keep terminal sequence test within defined keys

c5a5de9

Reset queued input before secret reads

fd56ef7

TimWolla reviewed Sep 27, 2026

View reviewed changes

Comment thread ext/standard/io_terminal.c Outdated

Comment thread ext/standard/io_terminal.c Outdated

Comment thread ext/standard/io_terminal.c Outdated

Comment thread ext/standard/io_terminal.c Outdated

Comment thread ext/standard/io_terminal.c

TimWolla reviewed Sep 27, 2026

View reviewed changes

Comment thread ext/standard/tests/terminal/terminal_read_secret.phpt Outdated

TimWolla reviewed Sep 27, 2026

View reviewed changes

prateekbhujel added 2 commits September 27, 2026 20:11

Address terminal review feedback

9a0ec24

Address remaining terminal review feedback

a62c87a

TimWolla reviewed Sep 27, 2026

View reviewed changes

Address follow-up terminal review feedback

99500f2

Fix terminal reflection test expectation

337395e

TimWolla reviewed Sep 27, 2026

View reviewed changes

Address terminal review feedback and fix macOS pty test

1f2f138

prateekbhujel mentioned this pull request Sep 27, 2026

[Console] Use ext-terminal when it is installed symfony/symfony#66173

Open

prateekbhujel added 4 commits September 28, 2026 15:46

Fix SIGWINCH handler sentinel checks

e612f66

Fix SIGWINCH handler sentinel checks

9eaaca4

Fix SIGWINCH handler sentinel checks

031b797

nicolas-grekas reviewed Sep 28, 2026

View reviewed changes

prateekbhujel added 3 commits September 28, 2026 21:25

Address Io\Terminal discussion feedback

7980ef8

Use shared raw-mode ownership for terminals

ae75619

Fix terminal_read_key_contracts expectation on Linux PTY EIO

c9a2813

TimWolla reviewed Sep 28, 2026

View reviewed changes

prateekbhujel added 4 commits September 29, 2026 01:33

Fix terminal timeout edge cases

18b695f

Stabilize readSecret PTY tests

baeda5b

DanielEScherzer reviewed Sep 29, 2026

View reviewed changes

prateekbhujel added 3 commits September 29, 2026 11:35

Address terminal review feedback

161defe

Keep braced terminal namespace

10d653a

Fix UTF-8 readKey timeout handling

e4792d8

Refine terminal contracts and add line input

e760af0

prateekbhujel added 6 commits September 30, 2026 10:30

Fix Windows readLine console mode restore and UTF-8 conversion checks

279010c

Handle Linux PTY master EIO as EOF during terminal readLine

daba0cf

Fix EAGAIN/EWOULDBLOCK compile portability in POSIX readLine

4ba14f4

Fix stale token cleanup on readLine and increase UTF-8 retain timeout

58262cc

Clean restoreMode comment type names and assert no-arg stale restoreMode

6925207

Wait for readability on EAGAIN in POSIX readLine to preserve submitte…

1fc4061

…d-line contract

Conversation

prateekbhujel commented Sep 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TimWolla left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DanielEScherzer left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

prateekbhujel commented Sep 27, 2026 •

edited

Loading