candy-mold

CI codecov Packagist Version License PHP

demo

Skeleton repo for bootstrapping a SugarCraft TUI app. Pour your model into the mold and you've got a working app.

composer create-project sugarcraft/candy-mold my-app
cd my-app
./bin/start

and you'll see a working counter. Replace src/Counter.php with your own Model, keep editing.

my-app/
├── composer.json # requires candy-core + candy-sprinkles
├── phpunit.xml
├── bin/start # entry point — runs Program(new Counter())
├── src/
│ └── Counter.php # demo Model with up/down/quit, styled border
└── tests/
 └── CounterTest.php

bin/start is just three meaningful lines: load the autoloader, instantiate your Model, hand it to Program::run(). The Program harness owns the event loop, render tick, signal handling, raw-mode setup, and alt-screen lifecycle — you only write Models.

A Model is three pure methods:

public function init(): ?\Closure; // optional startup Cmd (timers, fetch...)
public function update(Msg $msg): array; // [nextModel, ?Cmd]
public function view(): string; // current frame

The shape is borrowed verbatim from Bubble Tea / The Elm Architecture. State lives on the value object, transitions are pure functions, side effects (timers, HTTP, file I/O) get scheduled as Cmds rather than executed inline.

update() always returns a new Model rather than mutating $this. That's why the demo declares public readonly int $n — the only way to "change" the count is to construct a fresh Counter with the new value.

Add the dep, import its classes, return them from view(). They're all pure renderers on the same Style-based vocabulary.

composer install
vendor/bin/phpunit

The included tests/CounterTest.php shows how to test update() deterministically by constructing Msg objects directly. No event loop, no terminal, no mocking — just call methods and assert the returned tuple.

SugarCraft supports an opt-in panic handler that catches uncaught exceptions and displays a styled backtrace when the app crashes. To enable it, uncomment the panic handler block in bin/start:

// use SugarCraft\Log\Log;
// Log::installPanicHandler();

This feature requires sugarcraft/candy-log as a dependency.

MIT.