← All libraries

Open a master/slave PTY pair, spawn a child process with its stdin/stdout/stderr wired to the slave, and pump bytes / forward resizes between the host terminal and the child. Wraps the libc PTY syscalls (posix_openpt, grantpt, unlockpt, ptsname_r, ioctl(TIOCSWINSZ)) via ext-ffi — no shelling out to /usr/bin/script, no C extension to compile.

Install

composer require sugarcraft/candy-pty

Requires PHP 8.1+ with ext-ffi. ext-pcntl is optional — the lib polls waitpid() when pcntl is absent and SignalForwarder degrades to a no-op.

Open + spawn + drain

use SugarCraft\Pty\Pty;

$pty   = Pty::open();
$child = $pty->spawn(
    ['/bin/bash', '-c', 'echo $TERM; date'],
    ['TERM' => 'xterm-256color'],
    100, 30,                              // cols × rows
);

$pty->setBlocking(false);
$out = '';
while (!$child->exited()) {
    $chunk = $pty->read(4096, 0.05);     // 50ms timeout
    if ($chunk === null || $chunk === '') continue;
    $out .= $chunk;
}
$exit = $child->wait();
$pty->close();

Resize forwarding

use SugarCraft\Pty\SignalForwarder;
use SugarCraft\Core\Util\Tty;

SignalForwarder::attachSigwinch(
    $pty,
    fn () => Tty::size(),                // [cols => N, rows => N]
);
// Now every host SIGWINCH triggers $pty->resize($cols, $rows).

// For raw /dev/tty fds (no MasterPty object):
$ttyFd = \SugarCraft\Pty\Libc::lib()->open('/dev/tty', 0x0002); // O_RDWR
SignalForwarder::attachSigwinchToFd(
    $ttyFd,
    fn () => Tty::size(),
    fn (int $cols, int $rows) => null,  // optional post-resize callback
);

What's in the box

Use it for

• In-process SSH session hosting — drives CandyWish away from depending on host sshd; spawn the user's shell directly inside the SSH server process with full PTY control.
• Recorded TUI sessions — pair with CandyVcr to capture both the input bytes (typed into the master) and the rendered output (read back from the master).
• Test harnesses for ANSI-emitting CLIs — spawn the binary under test in a controlled PTY, pump fixture input, assert on the captured output via CandyVt's cell-grid.
• VHS-style demo recorders — run a script in a PTY, capture the byte stream + winsize, replay later.

Controlling terminal (Ctrl+C, job control)

Pass controllingTerminal: true to spawn() when you need Ctrl+C typed at the master to deliver SIGINT to the child — required for interactive shells (bash -i), editors (vim, less), and anything else that uses tty-driven job control.

$child = $pty->spawn(
    ['/bin/bash', '-i'],
    env: [...],
    controllingTerminal: true,    // claim slave as the child's ctty
);
$pty->write("\x03");              // Ctrl+C → SIGINT to the child

Routes the spawn through bin/pty-shim.php, which does setsid() + ioctl(0, TIOCSCTTY, 0) + pcntl_exec() between proc_open and the actual cmd. Requires ext-pcntl. Costs ~5-50 ms of shim startup per spawn — opt-in because non-interactive spawns don't benefit.

Known limitations

• Linux + macOS only. Windows ConPTY is a separate port and not in scope for this lib.

Source & demos

• Source on GitHub
• Full README
• Runnable examples
• Port of charmbracelet/x/xpty (Go upstream)

Try the quickstart →

API

Class	Method	Description
Pty	open()	Allocate master/slave PTY pair
Pty	spawn(cmd, env, cols, rows)	Spawn child process with PTY
Pty	read(len, timeout)	Read bytes from PTY
Pty	write(data)	Write bytes to PTY
Pty	resize(cols, rows)	Resize terminal window
Pty	size()	Get current terminal size
Pty	close()	Close the PTY
SignalForwarder	attachSigwinch(pty, provider)	Forward SIGWINCH to PTY resize
SignalForwarder	attachSigwinchToFd(fd, provider, onResize?)	Forward SIGWINCH to raw /dev/tty fd via TIOCSWINSZ
PosixPump	run(master, stdin, stdout, child?, opts?)	Run byte pump with optional PumpOptions callbacks
PumpOptions	withOnIdle(fn)	Register idle-tick callback (fires every stream_select timeout)
PumpOptions	withOnSigwinch(fn(cols, rows))	Register SIGWINCH callback (fires on terminal resize)
PumpOptions	withOnChildExit(fn(code))	Register child-exit callback
PumpOptions	withRecorder(recorder)	Attach session recorder (tee stdin/master bytes)
PumpOptions	sshDefault()	SSH-session-tuned preset — matches values hardcoded in InProcessTransport
Child	pid	Child process ID
Child	exited(), wait()	Check/await child exit
ControllingTerminal	claim(fd)	Claim a fd as controlling terminal via setsid() + ioctl(TIOCSCTTY)