← All 41 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.3+ with ext-ffi. ext-pcntl is optional — the lib polls waitpid() when pcntl is absent and SignalForwarder degrades to a no-op. ext-posix is optional too — kill() signals through Libc::kill(), which uses posix_kill() when it is loaded and libc kill(2) over FFI otherwise.

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;

$tty = new Tty(STDIN);                   // the host terminal
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: ['TERM' => 'xterm-256color'],
    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(cols = 80, rows = 24)	Allocate master/slave PTY pair (FD_CLOEXEC master, winsize applied at open)
Pty	spawn(cmd, env, cols, rows, controllingTerminal = false)	Spawn child process with PTY; winsize applied before the spawn and re-asserted after it
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()	Idempotent; always close(2)s the master fd and throws PtyException if that close (or the stream wrapper's fclose) fails
PtySystemFactory	new()	Build the platform PtySystem, honouring SUGARCRAFT_PTY_BACKEND (default() is a deprecated alias)
PosixSlavePty	spawn(cmd, env, cols = null, rows = null, controllingTerminal = false)	Spawn on a pair from PtySystem::open(); explicit geometry applied on every spawn, null keeps the pair's current size
Libc	kill(pid, signal)	posix_kill() when ext-posix is loaded, libc kill(2) over FFI otherwise
TermiosFactory	fallbackCount()	How many times the FFI termios backend fell back to stty (each fallback is also logged)
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)