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

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

Implements the Io\Terminal RFC (v0.6) for PHP 8.7.

Adds Io\Terminal\Terminal with terminal dimensions (getDimensions() returning Dimensions), raw-mode leases (enableRawMode() / restoreMode() with ModeToken), and key, line, and hidden input. It works on POSIX terminals and Windows consoles, and also accepts ordinary streams so input can be scripted in tests.

Raw-mode leases are tracked per logical terminal. They can be released in any order or through another Terminal wrapping the same terminal, and the last release restores the saved mode. enableRawMode() is #[\NoDiscard] because a discarded token releases its lease immediately.

Tests are in ext/standard/tests/terminal/. They cover lease ownership and restoration (including PTYs and fork), key decoding, timeouts, resize, line and secret input, and handoff between reads on the same instance.

The RFC is still under discussion.

DanielEScherzer

some initial thoughts

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

…m handling - Refactor public API to final Terminal and ModeToken classes under Nicolas's shared lease model - Implement explicit mode restoration via restoreMode(ModeToken $mode): void with transactional rollback - Implement bounded readiness and overall sequence deadlines for ordinary streams on POSIX and Windows - Unify byte-stream readSecret cancellation (Escape, Ctrl+C, Ctrl+D) and SS3/CSI controls across platforms - Harden CRLF lookahead across secret and line reading, preserving data CR before CRLF and at EOF - Isolate test seam hooks to debug/test builds (ZEND_DEBUG || PHP_TERMINAL_TEST_BUILD) - Add regression PHPT test suite covering fork isolation, failure injection, output flags, and streams

…e condition

…and EIO

Drop the readLine() suppression and the EIO-to-EOF conversion from fe88929; they were broader than the CI failure required and could hide real read errors.

…raw mode checks

… raw mode ISIG checks

…_checks

…etSize()

Mark enableRawMode() with NoDiscard so accidental disposal of the lease is visible. Document token destruction, cover the warning and explicit discard, and remove two setup calls that discarded their tokens.

TimWolla · 2026-11-08T18:19:41Z

I would drop the terminal_ from all test file names, that's redundant with the directory name.

Done, dropped the terminal_ prefix across all test files in the directory.

TimWolla · 2026-11-08T18:20:02Z

+--SKIPIF--
+<?php
+if (!class_exists(\Io\Terminal\Terminal::class)) die('skip Io\Terminal\Terminal not available');
+if (!class_exists(\Time\Duration::class)) die('skip Time\Duration not available');


Time\Duration is guaranteed to be available. And my understanding is that the terminal class is as well.

Removed the redundant class checks from the --SKIPIF-- sections.

TimWolla · 2026-11-08T18:22:52Z

+#ifdef PHP_WIN32
+typedef struct php_io_terminal_identity {
+	php_io_terminal_native_stream stream;
+	bool is_console;
+	bool is_non_tty_stream;
+	zend_ulong stream_res_id;
+	php_stream *php_stream_ptr;
+} php_io_terminal_identity;
+#else
+typedef struct php_io_terminal_identity {
+	php_io_terminal_native_stream stream;
+	dev_t dev;
+	bool has_dev;
+	pid_t sid;
+	bool has_sid;
+	bool is_non_tty_stream;
+	zend_ulong stream_res_id;
+	php_stream *php_stream_ptr;
+} php_io_terminal_identity;
+#endif


For readability I would suggest to only wrap the condition around the Unix/Windows differences and keep the common fields outside of the condition.

Cleaned up: moved the common fields outside the #ifdef PHP_WIN32 block, and did the same for the other platform conditionals in the file.

TimWolla · 2026-11-08T18:23:25Z

+#define PHP_IO_TERMINAL_READ_EOF      (-2)
+#define PHP_IO_TERMINAL_READ_ERROR    (-1)
+#define PHP_IO_TERMINAL_READ_TIMEOUT    0
+#define PHP_IO_TERMINAL_READ_SUCCESS    1
+#define PHP_IO_TERMINAL_READ_RESIZE     2


Make this an enum.

C doesn't allow switching on function pointers (and SIG_DFL/SIG_IGN expand to pointer casts), but I simplified this to a boolean check (handler != SIG_DFL && handler != SIG_IGN).

TimWolla · 2026-11-08T18:24:05Z

+	if (handler == NULL) {
+		return false;
+	}
+	if (handler == SIG_DFL) {
+		return false;
+	}
+	if (handler == SIG_IGN) {
+		return false;
+	}
+	return true;


switch() should be more readable.

C doesn't allow switching on function pointers (and SIG_DFL/SIG_IGN expand to pointer casts), but I simplified this to a one-line boolean check (handler != NULL && handler != SIG_DFL && handler != SIG_IGN).

TimWolla · 2026-11-08T18:29:08Z

+			unsigned char key;
+			int read_result = php_io_terminal_read_byte(fd, stream, poll_ctx, &key, timeout, true,
+				resize_handler_installed ? &resize_generation : NULL);
+			if (read_result == PHP_IO_TERMINAL_READ_RESIZE) {


Switched to switch (read_result).

TimWolla · 2026-11-08T18:30:22Z

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


Suggested change

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

zend_update_property_long(php_io_terminal_terminal_size_ce, Z_OBJ_P(ZEND_THIS), "cols", strlen("cols"), cols);

In new code prefer strlen().

Updated to strlen(), including the exception registration in MINIT.

…ensions() Avoid repeating the Terminal namespace in the size value object and use getDimensions() on Terminal. Also cover separate wrappers reading across a split CRLF secret delimiter.

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 Resolved

Comment thread ext/standard/io_terminal.c Resolved

Comment thread ext/standard/io_terminal.c Resolved

Comment thread ext/standard/io_terminal.c Resolved

Comment thread ext/standard/io_terminal.c Resolved

TimWolla reviewed Sep 27, 2026

View reviewed changes

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

TimWolla reviewed Sep 27, 2026

View reviewed changes

Comment thread ext/standard/tests/terminal/terminal_key_enum.phpt Resolved

Comment thread ext/standard/tests/terminal/terminal_read_key.phpt Resolved

Comment thread ext/standard/io_terminal.stub.php Resolved

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

Comment thread ext/standard/io_poll.c Resolved

Comment thread ext/standard/tests/terminal/terminal_read_key.phpt Resolved

Comment thread ext/standard/tests/terminal/terminal_create.phpt Resolved

Comment thread ext/standard/io_terminal.c Resolved

Comment thread ext/standard/io_terminal.c Resolved

Address follow-up terminal review feedback

99500f2

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 13 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

test(terminal): Fix GNU stty output parsing and eliminate PTY EOF rac…

f025a90

…e condition

fix(terminal): Suppress plain_wrapper stream notices on terminal EOF …

fe88929

…and EIO

fix(terminal): Narrow stream notice suppression to the POSIX byte reads

acf7cc2

Drop the readLine() suppression and the EIO-to-EOF conversion from fe88929; they were broader than the CI failure required and could hide real read errors.

fix(terminal): Align ordinary-stream readKey EOF to RFC and complete …

2af04bd

…raw mode checks

test(terminal): Use bounded PTY observation instead of fixed sleep in…

8573efd

… raw mode ISIG checks

test(terminal): Fix 32-bit intdiv TypeError in terminal_raw_mode_isig…

84b57e7

…_checks

prateekbhujel mentioned this pull request Oct 15, 2026

feat: read the log and profiles from the terminal dev-null-sh/dev-null.sh#92

Closed

prateekbhujel added 3 commits October 24, 2026 07:54

Fix zero-timeout escape decoding and preserve pending resize across g…

84a09f1

…etSize()

Fix terminal readKey EOF handling for incomplete UTF-8

03b201e

Warn when an Io\Terminal raw-mode token is discarded

2c841c8

Mark enableRawMode() with NoDiscard so accidental disposal of the lease is visible. Document token destruction, cover the warning and explicit discard, and remove two setup calls that discarded their tokens.

TimWolla reviewed Nov 8, 2026

View reviewed changes

prateekbhujel added 4 commits November 9, 2026 08:49

Rename Io\Terminal\TerminalSize to Dimensions and getSize() to getDim…

a88859d

…ensions() Avoid repeating the Terminal namespace in the size value object and use getDimensions() on Terminal. Also cover separate wrappers reading across a split CRLF secret delimiter.

Address inline review feedback in io_terminal.c and terminal tests

c93c75b

Fix logical-op warning in php_io_terminal_is_callable_handler

d08c164

Support sequenceTimeout parameter in Terminal::readSecret()

f603bbb

	zend_update_property_long(php_io_terminal_terminal_size_ce, Z_OBJ_P(ZEND_THIS), "cols", sizeof("cols") - 1, cols);
	zend_update_property_long(php_io_terminal_terminal_size_ce, Z_OBJ_P(ZEND_THIS), "cols", strlen("cols"), cols);

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

DanielEScherzer left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

NattyNarwhal commented Sep 29, 2026

Uh oh!

prateekbhujel commented Sep 30, 2026

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 Nov 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

prateekbhujel commented Sep 27, 2026 •

edited

Loading

prateekbhujel Nov 9, 2026 •

edited

Loading