PHPackages                             sugarcraft/candy-input - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. sugarcraft/candy-input

ActiveLibrary[Utility & Helpers](/categories/utility)

sugarcraft/candy-input
======================

Terminal escape sequence decoder for keyboard (legacy + Kitty progressive) and mouse (SGR 1006). Provides InputDriver interface and EscapeDecoder implementation. Unblocks sugar-readline migration to real-TTY input.

03.1k↓11.4%PHP

Since Jul 12Pushed 1w agoCompare

[ Source](https://github.com/sugarcraft/candy-input)[ Packagist](https://packagist.org/packages/sugarcraft/candy-input)[ RSS](/packages/sugarcraft-candy-input/feed)WikiDiscussions master Synced 1w ago

READMEChangelogDependenciesVersions (1)Used By (0)

CandyInput
==========

[](#candyinput)

Terminal escape sequence decoder for keyboard (legacy + Kitty progressive keyboard protocol) and mouse (SGR 1006). Provides the `InputDriver` interface and `EscapeDecoder` implementation.

Overview
--------

[](#overview)

`candy-input` is the missing input layer for SugarCraft — it decodes raw TTY bytes into structured `Event` objects that programs can switch on. It handles:

- **Plain ASCII keys** — letters, digits, punctuation, control codes
- **Legacy escape sequences** — F1–F12, arrow keys, Home/End/PgUp/PgDn, Insert, Delete, Backspace, Tab, Enter, Escape
- **Kitty keyboard protocol** — disambiguation flags via CSI `?u`, including key release events
- **SGR 1006 mouse** — press, release, drag, and scroll with modifier support
- **Focus events** — DECSET 1004 via `CSI I` / `CSI O`
- **Bracketed paste** — `CSI 200 ~` … `CSI 201 ~` with 1 MiB safety cap

Quickstart
----------

[](#quickstart)

```
use SugarCraft\Input\EscapeDecoder;
use SugarCraft\Input\Driver\StreamInputDriver;
use SugarCraft\Input\Event\KeyEvent;
use SugarCraft\Input\Event\MouseEvent;

$decoder = new EscapeDecoder();
$driver  = new StreamInputDriver(STDIN);

// Non-blocking read loop
while (true) {
    $event = $driver->read();
    if ($event === null) {
        continue; // non-blocking empty or EOF
    }

    match (true) {
        $event instanceof KeyEvent  => handleKey($event),
        $event instanceof MouseEvent => handleMouse($event),
        default                      => handleOther($event),
    };
}
```

Installation
------------

[](#installation)

```
composer require sugarcraft/candy-input
```

API
---

[](#api)

### EscapeDecoder

[](#escapedecoder)

```
$decoder = new EscapeDecoder();

// Decode a byte buffer — returns 0+ Events, buffers partial sequences
$events = $decoder->decode($bytes);

// Get unconsumed remainder after decode()
$remainder = $decoder->remainder();

// Clear the partial-sequence buffer
$decoder->reset();
```

### InputDriver

[](#inputdriver)

```
interface InputDriver {
    /** Returns the next Event, or null on EOF / non-blocking empty */
    public function read(): ?Event;
}
```

Event types
-----------

[](#event-types)

EventKey fields`KeyEvent``key`, `modifiers`, `raw``MouseEvent``x`, `y`, `button`, `action`, `modifiers``FocusEvent``gained``PasteEvent``content``ResizeEvent``cols`, `rows`Key constants (KeyModifier)
---------------------------

[](#key-constants-keymodifier)

`Shift`, `Ctrl`, `Alt`, `Super`, `Hyper`, `Meta`, `CapsLock`, `NumLock` — combine with bitwise OR.

No upstream parallel
--------------------

[](#no-upstream-parallel)

This is a pioneering implementation for PHP TUI — there is no direct upstream to port. It decodes the same sequences that the kernel and terminal emulators produce.

License
-------

[](#license)

MIT

###  Health Score

27

—

LowBetter than 46% of packages

Maintenance64

Regular maintenance activity

Popularity24

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity11

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/b1036e0717211b8030b83cbe729e8ba6ba442fdbd5285fb97a39d7dcfe339342?d=identicon)[detain](/maintainers/detain)

---

Top Contributors

[![detain](https://avatars.githubusercontent.com/u/1364504?v=4)](https://github.com/detain "detain (34 commits)")

### Embed Badge

![Health badge](/badges/sugarcraft-candy-input/health.svg)

```
[![Health](https://phpackages.com/badges/sugarcraft-candy-input/health.svg)](https://phpackages.com/packages/sugarcraft-candy-input)
```

###  Alternatives

[laravolt/indonesia

Package Laravel yang berisi data Provinsi, Kabupaten/Kota, Kecamatan, dan Keluarahan/Desa di seluruh Indonesia.

668212.3k1](/packages/laravolt-indonesia)[mhor/php-mediainfo

PHP wrapper around the mediainfo command

120597.4k8](/packages/mhor-php-mediainfo)[advoor/nova-editor-js

A Laravel Nova field bringing EditorJs magic to Nova.

92219.3k3](/packages/advoor-nova-editor-js)[ohdearapp/ohdear-pulse

Integrate Oh Dear with Laravel Pulse

26190.0k](/packages/ohdearapp-ohdear-pulse)[verbb/hyper

A user-friendly links field for Craft.

24147.8k12](/packages/verbb-hyper)[modstore/laravel-enum-js

Package to generate javascript versions of your PHP enum files to be used in your js builds etc.

15157.4k](/packages/modstore-laravel-enum-js)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)