https://github.com/detain/sugarcraft
🍬🍭 Monorepo: 16 PHP TUI libraries — ports of 🫧 BubbleTea, 🎨 Lipgloss, 🍬 Gum, 💎 Glamour, ✨ Glow + more. PHP 8.1+, ReactPHP async, composer-installable.
https://github.com/detain/sugarcraft
ansi bubbletea bubbletea-port charmbracelet composer console-app elm-architecture framework gum-port hacktoberfest lipgloss-port monorepo php-library php81 phptui reactphp terminal-ui tui tui-framework
Last synced: about 1 month ago
JSON representation
🍬🍭 Monorepo: 16 PHP TUI libraries — ports of 🫧 BubbleTea, 🎨 Lipgloss, 🍬 Gum, 💎 Glamour, ✨ Glow + more. PHP 8.1+, ReactPHP async, composer-installable.
- Host: GitHub
- URL: https://github.com/detain/sugarcraft
- Owner: detain
- License: mit
- Created: 2026-05-01T22:31:32.000Z (about 1 month ago)
- Default Branch: master
- Last Pushed: 2026-05-02T22:20:08.000Z (about 1 month ago)
- Last Synced: 2026-05-02T23:12:58.175Z (about 1 month ago)
- Topics: ansi, bubbletea, bubbletea-port, charmbracelet, composer, console-app, elm-architecture, framework, gum-port, hacktoberfest, lipgloss-port, monorepo, php-library, php81, phptui, reactphp, terminal-ui, tui, tui-framework
- Language: PHP
- Homepage: https://detain.github.io/sugarcraft/
- Size: 11 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# SugarCraft
[](https://github.com/detain/sugarcraft/actions/workflows/ci.yml)
[](https://app.codecov.io/gh/detain/sugarcraft)
[](LICENSE)
[](https://www.php.net/)
[](CONTRIBUTING.md)
PHP ports of the [Charmbracelet](https://charm.sh) TUI ecosystem (plus
[bubblezone](https://github.com/lrstanley/bubblezone),
[ntcharts](https://github.com/NimbleMarkets/ntcharts), and a small
SugarCraft-flavoured sweetshop of original libraries) — composer-installable,
PHP 8.1+, async on ReactPHP.
🌐 **Website:** [sugarcraft.github.io](https://sugarcraft.github.io/) — library matrix, quickstart, comparison page.
```sh
composer require candycore/candycore
```
## What's in the box
Sixteen libraries grouped by layer:
| | Library | Role |
|---|---|---|
| 
| **[CandyCore](candy-core/)** | Elm-architecture TUI runtime — `Model` / `Msg` / `Cmd` / `Program` (incl. cursed cell-diff renderer). Port of [bubbletea](https://github.com/charmbracelet/bubbletea). |
| 
| **[CandySprinkles](candy-sprinkles/)** | Declarative styling + layout — `Style`, `Border`, `Table`, `List`, `Tree`, `Layout::join`, `Place`, `Canvas` (multi-layer compositor). Port of [lipgloss](https://github.com/charmbracelet/lipgloss). |
| 
| **[HoneyBounce](honey-bounce/)** | Damped spring physics + Newtonian projectile sim. Port of [harmonica](https://github.com/charmbracelet/harmonica). |
| 
| **[CandyZone](candy-zone/)** | Mouse-zone tracker — wrap rendered chunks, get back bounding boxes. Port of [bubblezone](https://github.com/lrstanley/bubblezone). |
| 
| **[SugarBits](sugar-bits/)** | 14 components: TextInput, TextArea, ItemList, Table, Viewport, FilePicker, Progress, Spinner, Cursor, Help, Key, Paginator, Stopwatch, Timer. Port of [bubbles](https://github.com/charmbracelet/bubbles). |
| 
| **[SugarCharts](sugar-charts/)** | Canvas + Sparkline, Bar, Line, Heatmap, Scatter, TimeSeries, Streamline, Waveline, OHLC, Picture (Sixel/Kitty/iTerm2). Port of [ntcharts](https://github.com/NimbleMarkets/ntcharts). |
| 
| **[SugarPrompt](sugar-prompt/)** | Form library — Note, Input, Confirm, Select, MultiSelect, Text, FilePicker; multi-page Groups; 6 themes. Port of [huh](https://github.com/charmbracelet/huh). |
| 
| **[CandyShell](candy-shell/)** | Composer-installable CLI of all 13 subcommands (choose, confirm, file, filter, format, input, join, log, pager, spin, style, table, write). Port of [gum](https://github.com/charmbracelet/gum). |
| 
| **[CandyShine](candy-shine/)** | Markdown → ANSI renderer with word-wrap, OSC 8 hyperlinks, 8 themes. Port of [glamour](https://github.com/charmbracelet/glamour). |
| 
| **[CandyKit](candy-kit/)** | CLI presentation helpers — StatusLine, Banner, Section, Stage, HelpText. Port of [fang](https://github.com/charmbracelet/fang). |
| 
| **[CandyFreeze](candy-freeze/)** | Code → SVG screenshot generator (no `ext-gd` required). Port of [freeze](https://github.com/charmbracelet/freeze). |
| 
| **[SugarGlow](sugar-glow/)** | Markdown CLI viewer / pager. Port of [glow](https://github.com/charmbracelet/glow). |
| 
| **[SugarSpark](sugar-spark/)** | ANSI escape-sequence inspector. Port of [sequin](https://github.com/charmbracelet/sequin). |
| 
| **[CandyWish](candy-wish/)** | SSH server middleware — Logger, Auth, RateLimit, BubbleTea (mount a CandyCore Program over `ForceCommand`). Port of [wish](https://github.com/charmbracelet/wish). |
| 
| **[SugarWishlist](sugar-wishlist/)** | TUI directory of SSH endpoints — YAML/JSON config + `pcntl_exec` into the chosen `ssh`. Port of [wishlist](https://github.com/charmbracelet/wishlist). |
| 
| **[CandyMetrics](candy-metrics/)** | Telemetry primitives — counters, gauges, histograms with InMemory / JSON / StatsD / Prometheus textfile / Multi backends, plus a CandyWish session middleware. Port of [promwish](https://github.com/charmbracelet/promwish). |
## Apps built on the stack
| | App | Role |
|---|---|---|
| 
| **[CandyMold](candy-mold/)** | `composer create-project candycore/candy-mold my-app` — bootstrap skeleton with a working counter Model. Port of [bubbletea-app-template](https://github.com/charmbracelet/bubbletea-app-template). |
| 
| **[CandyTetris](candy-tetris/)** | Tetris clone — SRS rules, 7-bag, ghost piece, NES scoring, level-driven gravity. Port of [tetrigo](https://github.com/Broderick-Westrope/tetrigo). |
| 
| **[SuperCandy](super-candy/)** | Dual-pane file manager — Midnight Commander style, multi-select, sort, delete-with-confirm. Port of [superfile](https://github.com/yorukot/superfile). |
| 
| **[SugarCrush](sugar-crush/)** | AI coding-assistant chat shell — pluggable backend (EchoBackend offline; CommandBackend for Anthropic / OpenAI / Ollama via a wrapper script). Port of [crush](https://github.com/charmbracelet/crush). |
| 
| **[SugarStash](sugar-stash/)** | Three-pane git TUI — status / branches / log, single-key stage / unstage; shells out to `git` for every mutation. Port of [lazygit](https://github.com/jesseduffield/lazygit). |
| 
| **[CandyQuery](candy-query/)** | Terminal SQLite browser — list tables, browse rows, run ad-hoc queries (PDO + `:memory:` test fixtures). Port of [lazysql](https://github.com/jorgerojas26/lazysql). |
| 
| **[SugarTick](sugar-tick/)** | Privacy-first coding-time tracker — JSONL on disk, SugarCharts-driven dashboard, no cloud / no MongoDB. Port of [TakaTime](https://github.com/Rtarun3606k/TakaTime). |
| 
| **[CandyMines](candy-mines/)** | Minesweeper — first-click safety, recursive flood-fill, flag toggle, win/lose detection, deterministic-RNG injectable. Port of [go-sweep](https://github.com/maxpaulus43/go-sweep). |
| 
| **[CandyFlip](candy-flip/)** | ASCII GIF viewer — ext-gd decode, downsample to a cell grid, render as ANSI 24-bit blocks or a luminance-ramp. Port of [gifterm](https://github.com/namzug16/gifterm). |
| 
| **[HoneyFlap](honey-flap/)** | Flappy-Bird-style game — bird motion is a HoneyBounce projectile, pipes scroll left at a fixed cell rate. Port of [flapioca](https://github.com/kbrgl/flapioca). |
Each library has its own `README.md` with usage examples and a deep dive into
its public API.
## Quickstart — a counter app
```php
use CandyCore\Core\{Cmd, KeyType, Model, Msg, Program};
use CandyCore\Core\Msg\KeyMsg;
final class Counter implements Model
{
public function __construct(public readonly int $n = 0) {}
public function init(): ?\Closure { return null; }
public function update(Msg $msg): array
{
if ($msg instanceof KeyMsg && $msg->type === KeyType::Char && $msg->rune === 'q') {
return [$this, Cmd::quit()];
}
return [
$msg instanceof KeyMsg && $msg->type === KeyType::Up
? new self($this->n + 1)
: ($msg instanceof KeyMsg && $msg->type === KeyType::Down
? new self($this->n - 1)
: $this),
null,
];
}
public function view(): string { return "n = {$this->n}\n↑ ↓ to count, q to quit\n"; }
}
(new Program(new Counter()))->run();
```
## Architecture
- **PHP 8.1+** — fibers, readonly props, enums, `match`, intersection types.
- **Runtime**: ReactPHP event loop. Mirrors goroutine semantics for input,
signals, render tick, command execution.
- **Style**: PSR-12 + readonly DTOs. Every `Style`, `Model`, etc. is
immutable — `with*()` returns a new instance.
- **Testing**: PHPUnit 10. Snapshot ANSI tests for renderers; scripted-input
event tests for the runtime.
- **Layout**: monorepo during the porting phase. Each library will split
into its own repo at v1.0.
## Status
Every library in the table above is **at v1**. The full surface of every Go
counterpart that PHP can reasonably express (modulo the niche items called
out in `CONVERSION.md` § Phase audit) has been ported. See
[CONVERSION.md](./CONVERSION.md) for the full roadmap, per-library status,
and the v2-parity sweep against Bubble Tea v2 / Lipgloss v2 / Bubbles v2.
## Running the test suites
The umbrella package is a metapackage; each library has its own
`composer.json` + `vendor/`. To test everything:
```sh
for d in candy-core candy-sprinkles honey-bounce candy-zone sugar-bits \
sugar-charts sugar-prompt candy-shell candy-shine candy-kit \
candy-freeze sugar-glow sugar-spark \
candy-wish sugar-wishlist candy-metrics \
candy-mold candy-tetris super-candy sugar-crush \
sugar-stash candy-query sugar-tick candy-mines candy-flip honey-flap; do
(cd "$d" && composer install --quiet && vendor/bin/phpunit) || exit 1
done
```
## Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md). Bugs, feature requests, and
ports of additional Charmbracelet (or compatible) libraries welcome.
For security issues, see [SECURITY.md](./SECURITY.md).
## License
[MIT](./LICENSE).
---
made with sugar · sweet to build · fun to use