SugarCraft — sweet to build, fun to use

Terminal UIs that taste like candy.

SugarCraft is a PHP-native TUI ecosystem — forty-two libraries and twenty-two apps (sixty-four packages total). MVC-style Model–Update–View runtime, declarative styling, animation, charts, forms, SSH-served apps, telemetry, file managers, an AI chat shell. Composer-installable, PHP 8.3+, async on ReactPHP.

42libraries
22apps
296VHS demos
PHP 8.3+async / ReactPHP
MITlicensed

Every layer of the terminal stack — in PHP.

Click an icon to jump to its detail page. Every package is published independently, ships its own examples and PHPUnit suite, and shares a single styling vocabulary so they compose without glue code.

Built for the things Symfony Console can't do.

Persistent render loops, mouse + keyboard, alt-screen, async work without blocking the UI, multi-tenant SSH-served TUIs, charts and sparklines, animated spinners, multi-page forms, Markdown rendered straight to ANSI. The boring parts of CLI tooling — argv parsing, exit codes — pair perfectly with whatever Console framework you already use.

Forty-two libraries, one ecosystem.

Each library has its own composer package, README, examples, and PHPUnit suite. Pull just the ones you need — or grab the umbrella metapackage and get the lot. The complete catalog lives on the libraries page.

Twenty-two apps built on the stack.

Standalone executables — CLI tools (prompts, markdown, screenshots), full TUIs (file manager, git, SQLite, AI chat, games), and a project starter — the starter you scaffold, not install. Install via Composer, run as a CLI binary. Every detail page carries controls, architecture, and demo recordings — the showcase below and the full catalog on the apps page.

Five layers, no surprises.

SugarCraft is a layered architecture with one responsibility per layer. Dependencies flow one way through the stack, so you can grab as much or as little as you need.

1. Foundation
SugarCraft::Util — Ansi, Color, ColorProfile, Width, Tty — plus the SugarPty master/slave PTY primitives (POSIX FFI, Windows ConPTY). Depended on by everything below.
2. Render + physics
SugarStyle — styling, SugarSpring — spring physics. Pure rendering / pure math — no I/O.
3. Runtime
SugarCraft — Model / Msg / Cmd / Program. An MVC-style Model–Update–View loop on ReactPHP with command and subscription hooks, driving real terminals through the layer-1 PTY primitives.
4. Components
SugarWidgets (components), SugarCharts (charts), SugarForms (forms), SugarMouse (mouse zones). Composable widgets that drop into your Model.
5. Tooling libs + apps
Tooling libs: SugarMarkdown (markdown → ANSI), SugarCli (CLI chrome), SugarSshServer (SSH), SugarMetrics (telemetry), SugarLog (logging), SugarColorprofile (color detection), SugarAnimation (ANSI/GIF animation toolkit).
CLI apps: CandyScriptui (one-shot CLI helpers), CandyMdview (markdown), CandyAnsiInspect (ANSI inspector), CandyCodeshot (code → SVG), CandySshLauncher (SSH launcher), CandyGitServer (git server), CandyKv (key/value store), CandyMail (email sender), CandyVcr (session record/replay).
TUI apps: CandyStarter, CandyTetris, CandyFiles, CandyCode, CandyGit, CandySql, CandyCodetime, CandyMinesweeper, CandyTop, CandyFlappy, CandyGifView (GIF viewer), CandyImage (image viewer).
Web UI: CandyCodeWeb (browser face of CandyCode).
⚡

Async-first

ReactPHP event loop under the hood. Cmds are closures dispatched on the loop; the render thread never blocks on I/O.

📐

Immutable values

Immutable value objects across the fleet — with*() returns a new instance. sugar-style carries a documented naming exception (bare bold()/fg() builders over a private with()).

🧪

Testable by design

Pure update functions and snapshot ANSI tests. No tmp dirs, no mocks for the renderer — just assert against the frame.

🎨

One styling vocabulary

Every package speaks SugarCraft\Style\Style. Mix SugarMarkdown output into a SugarWidgets Viewport, wrap that with a SugarStyle Border — they all compose.

🔐

SSH the easy way

SugarSshServer leans on ForceCommand. sshd handles auth, ciphers, fail2ban, audit logs — you get a clean middleware programming model.

📦

Pure-PHP by default

No build step, and the base flow needs nothing beyond a standard PHP-CLI. Only named features hard-gate an extension — ext-ffi for PTYs, ext-gd for imaging, ext-sqlite3 for storage backends, ext-mbstring/ext-intl where Unicode is load-bearing. ext-pcntl, ext-ssh2, ext-curl stay optional suggestions with clean fallbacks.

See them run.

VHS-recorded GIFs of every interactive demo, regenerated on every push that touches the corresponding source. These are the headliners; click into any library page for its full set.

Accessibility note: the previews are looping GIF recordings, content rather than decoration — deliberately excluded from the site's blanket reduced-motion rule, since no browser can pause an animated <img>. A reduced-motion preference still stops this site's own transitions and animations, and the full-size lightbox view is opt-in and closes on demand. The TUIs themselves honor REDUCE_MOTION / PREFERS_REDUCED_MOTION where supported (sugar-spring, sugar-colorprofile, sugar-toast, sugar-video).

From composer require to a working counter app.

Install the umbrella, drop the snippet below into a file, php counter.php. ↑ ↓ to count, q to quit.

Before you install

sugarcraft/* packages publish from dev-master until their first tags are cut, so a Composer project left on the default stable minimum-stability cannot resolve them. Add "minimum-stability": "dev", "prefer-stable": true to your root composer.json (or suffix your require with @dev).

1. Install

composer require sugarcraft/sugarcraft

2. Write the model

<?php

require __DIR__ . '/vendor/autoload.php';

use SugarCraft\Core\{Cmd, KeyType, Model, Msg, Program, Subscriptions};
use SugarCraft\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 [match (true) {
            $msg instanceof KeyMsg && $msg->type === KeyType::Up   => new self($this->n + 1),
            $msg instanceof KeyMsg && $msg->type === KeyType::Down => new self($this->n - 1),
            default => $this,
        }, null];
    }

    public function view(): string { return "n = {$this->n}\n↑ ↓ to count, q to quit\n"; }

    public function subscriptions(): ?Subscriptions { return null; }
}

(new Program(new Counter()))->run();

3. Run it

php counter.php

Want a project skeleton instead?

composer create-project sugarcraft/candy-starter my-app --stability=dev scaffolds a runnable counter app with PHPUnit wired up — see CandyStarter.

Why pick SugarCraft?

Three flavours of "build a TUI in PHP" — pick the row that matches your project's needs. (Full reasoning on the comparison page.)

Capability SugarCraft Symfony Console readline / raw
MVC-style Model–Update–View runtime (Model / Msg / Cmd) ✓ — —
Async event loop (ReactPHP) ✓ partial —
Declarative styling (CSS-like flexbox / borders) ✓ manual —
Composable form library ✓ (SugarForms) — —
Mouse + key bindings ✓ — —
SSH-served apps (multi-tenant) ✓ (SugarSshServer) — —
Charts / sparklines / heatmaps ✓ (SugarCharts) — —
One-shot CLI prompts ✓ (CandyScriptui) primitive —
Markdown → ANSI rendering ✓ (SugarMarkdown) — —
Code → SVG screenshots ✓ (CandyCodeshot) — —
Telemetry primitives (StatsD / Prom) ✓ (SugarMetrics) — —