sugarcraft/sugar-readline

PHP port of erikgeiser/promptkit — interactive line-editing prompt library. Supports text input with validation/completion/hidden-password mode, selection prompts with filtering/pagination/cursor navigation, confirmation prompts, and textarea multi-line input.

v0.2.0 2026-05-07 01:29 UTC

Requires

• php: ^8.1

Requires (Dev)

• phpunit/phpunit: ^10.5

MIT

• Joe Huss

• input
• prompt
• readline
• interactive
• selection
• tui
• sugarcraft

README

SugarReadline

PHP port of erikgeiser/promptkit — interactive line-editing prompt library for terminal UIs.

Features

• TextPrompt — single-line input with validation, auto-completion, hidden/password mode, char limit, default value
• SelectionPrompt — filtered list with cursor navigation and pagination
• MultiSelectPrompt — filtered multi-choice with min/max enforcement and FIFO rollover at the cap
• ConfirmationPrompt — yes/no with customizable labels, decoupled select-vs-submit
• TextareaPrompt — multi-line text input with line/column cursor and optional max-line cap
• Pure renderer — every method returns a new immutable instance; view() returns ANSI strings, value() returns the data

Install

composer require sugarcraft/sugar-readline

Quick Start

Text Prompt

use SugarCraft\Readline\{Key, TextPrompt};

$p = TextPrompt::new('Enter your name: ')
    ->withDefault('Anonymous')
    ->withCompletions(['Alice', 'Bob', 'Carol']);

$p = $p->handleChar('A')->handleChar('l')->handleKey(Key::Tab)->submit();
echo $p->value();  // 'Alice'

Selection Prompt

use SugarCraft\Readline\SelectionPrompt;

$p = SelectionPrompt::new('Choose a fruit:', ['Apple', 'Banana', 'Cherry', 'Date'])
    ->withFilter('an');                 // Banana matches
echo $p->selectedValue();              // 'Banana'

Multi-Select Prompt

use SugarCraft\Readline\{Key, MultiSelectPrompt};

$p = MultiSelectPrompt::new('Pick:', ['A', 'B', 'C'])
    ->withMinSelections(1)
    ->handleKey(Key::Space)              // mark A
    ->handleKey(Key::Down)
    ->handleKey(Key::Space)              // mark B
    ->handleKey(Key::Enter);             // submit (min satisfied)

print_r($p->selectedValues());          // ['A', 'B']

Confirmation Prompt

use SugarCraft\Readline\{ConfirmationPrompt, Key};

$p = ConfirmationPrompt::new('Delete file?')
    ->handleKey('n')                     // selects No (does not auto-submit)
    ->handleKey(Key::Left)               // changes mind back to Yes
    ->submit();
echo $p->result() ? 'yes' : 'no';       // 'yes'

Key Bindings

The SugarCraft\Readline\Key class exposes symbolic constants for every supported key.

• Key::Left / Key::Right — move cursor (text input)
• Key::Up / Key::Down — navigate selection list / change line in textarea
• Key::PageUp / Key::PageDown — page through long lists
• Key::Home / Key::End — jump within the current line / list
• Key::Enter — submit text or select current choice
• Key::Space — toggle mark in multi-select
• Key::Tab — auto-complete or toggle confirmation value
• Key::Backspace / Key::Delete — delete characters
• Key::CtrlU / Key::CtrlK — delete to start / end of line
• Key::Escape / Key::CtrlC — abort

Submit / Abort Semantics

Each prompt is a state machine with three states: pending, submitted, aborted.

• submit() finalises the prompt; for MultiSelectPrompt it only succeeds when canSubmit() is true.
• abort() (or feeding Key::Escape / Key::CtrlC) discards the prompt; value() / selectedValues() then return empty.
• isSubmitted() / isAborted() report status; currentValue() (Confirmation) and selectedValue() (Selection) reflect the current cursor regardless of submission state.

License

MIT