KeyMatcher

Keyboard input matching for TUI renderers and loops. The PHP analog of pi-tui's `matchesKey()` + `Key` helper. Turns the raw byte sequences a terminal emits (legacy ANSI escapes, single control bytes, printable chars) into a stable key id like `'ctrl+c'`, `'shift+tab'`, `'up'`, and lets callers compare them against human-readable identifiers (`Key::ctrl('c')`, `'up'`, `'shift+tab'`). The id format is the same pi-tui uses, so behavior transfers: modifiers are listed in a fixed order (`ctrl+shift+alt+<key>`), bare letters are lowercased, and the named special keys (`enter`, `escape`, `tab`, …) are the same strings. Usage: if (KeyMatcher::matches($raw, Key::ctrl('c'))) { ... } if (KeyMatcher::matches($raw, 'up')) { ... } if (KeyMatcher::matches($raw, Key::shift('tab'))) { ... } The matcher does NOT depend on the Kitty keyboard protocol — it recognizes the legacy ANSI sequences every terminal emits by default, which is what `RetainedTuiLoop::readKey()` already consumes. Adding Kitty support later means extending {@see normalize()}, not the callers.

public static function matches(string $raw, string $id): bool

Whether `$raw` (the byte sequence read from the terminal) matches the given key id. The id may use any of the formats produced by {@see Key::*} or the bare string aliases (`'enter'`, `'ctrl+c'`). Modifier order in `$id` is normalized before comparison so `'ctrl+shift+p'` and `'shift+ctrl+p'` match the same input.

Parameters

public static function normalize(string $raw): string

Normalizes a raw byte sequence into the canonical key id. Returns an empty string for empty input so callers can skip no-op reads.

Parameters

public static function canonicalId(string $id): string

Canonicalizes a human-readable id so modifier order and aliases do not fragment comparisons. `'esc'` becomes `'escape'`; `'return'` becomes `'enter'`; modifiers are reordered to `ctrl+shift+alt+`.

Parameters