Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01X3cUrphmz1MoDiCrUbAHuo
6.7 KiB
CLI apps: applications in the terminal
Besides games, desktop apps (docs/tauri.md) and graphic apps (docs/gui.md), JumPHP makes CLI apps: programs that
live in the terminal. Commands (todo add "Buy milk") with Symfony Console,
and full-screen text screens (lists, fields, progress, keyboard) with symfony/tui,
Fabien Potencier's terminal UI component. The same commands as games: run, test, shot, one executable per system.
Example: games/hello-cli (a task list).
bin/jumphp cli:new todo "Todo" # apps/todo from skeleton-cli/ (config/project.yaml: kind: cli)
bin/jumphp install todo
bin/jumphp run todo # the full-screen screen (in this terminal)
bin/jumphp run todo add "Buy milk" # a command and its arguments
bin/jumphp test todo # php -l + phpstan + phpunit + smoke test (php app.php list)
JUMPHP_KEYS='[[1,"a"],[1.3,"Milk"],[1.6,"\r"]]' bin/jumphp shot todo 2.5 # the screen as text
bin/jumphp export:standalone todo --linux --windows --macos
The project
apps/todo/
app.php require vendor/autoload.php; exit(App\Main::boot(__DIR__)->run());
config/project.yaml id, title, version, description, kind: cli
src/Main.php the Console application: its commands, the default one, the data folder
src/Command/*.php one command per class (#[AsCommand('add', 'Adds a task')])
src/Ui/*.php full-screen screens (symfony/tui)
tests/ CommandsTest (ApplicationTester), TaskScreenTest (VirtualTerminal)
var/ the data while developing (the user's data folder once exported)
- No command: the full-screen screen when the output is a terminal, the plain list when it is a pipe or a file
(
Main::__construct,stream_isatty(STDOUT)): everything stays usable in scripts. - Data:
Main::boot()givesJUMPHP_VAR(set by the exported executable:~/.local/share/<id>,%APPDATA%\<id>,~/Library/Application Support/<id>), elsevar/. - Paths typed by the user are relative to the folder they ran the program from: the exported executable unpacks
the app in a cache folder,
Main::boot()goes back toJUMPHP_CWD.
Screens (symfony/tui)
A Tui holds widgets (TextWidget, SelectListWidget, InputWidget, EditorWidget, ProgressBarWidget,
MarkdownWidget, SettingsListWidget, LoaderWidget...), runs its own loop (run() until stop()), and gives the
keys to the focused widget (setFocus()); a widget's onInput() sees them first (a, d, q in the example).
Events: onSelect, onSubmit, onCancel, onChange. Timers: scheduleInterval($callback, $seconds) (never
sleep()). Styles: StyleSheet (Tailwind-like classes, TailwindStylesheet). The component is still marked
experimental by Symfony: pin its version in composer.json when the app is done.
Tests
- Commands:
Symfony\Component\Console\Tester\ApplicationTesteron(new Main($dir))->console. - Screens: the screen on a
VirtualTerminal($columns, $rows):$tui->start(); $tui->tick();, then$terminal->simulateInput("\x1b[B")(down;"\r"Enter,"\x1b"Escape,"\x03"Ctrl+C) and$tui->tick(), and read what the user sees:$buffer = new ScreenBuffer($columns, $rows); $buffer->write($terminal->getOutput()); $buffer->getScreen(). bin/jumphp shot <app> [seconds] [out.txt]runs the real program in a pseudo-terminal (JUMPHP_COLUMNSxJUMPHP_ROWS, 100 x 30), typesJUMPHP_KEYS([[seconds, "text"], ...]), passesJUMPHP_ARGS, and writes the screen as text invar/screenshots/screen.txt(a fresh data folder each time).
On jumphp.net
Published on the playground (a project of kind cli), the app's Play is a terminal in the page: each command line
typed there runs app.php with those arguments in the browser's PHP (WebAssembly), with the app's own Composer
packages (the playground installs its composer.json's require from Packagist: no scripts nor plugins). Its output
keeps its colours (FORCE_COLOR); var/ (its data) is kept in the visitor's browser. The playground runs the app's
tests (tests/) with the same packages.
It is interactive like a real terminal: PHP runs in a Web Worker and waits for what is typed (a SharedArrayBuffer; the page is cross-origin isolated by its COOP / COEP / Document-Isolation-Policy headers).
- Questions (Symfony's
ask(),confirm(),choice(), anyfgets(STDIN)): the page edits and echoes the line, Enter gives it to PHP; Ctrl+D or Ctrl+C is the end of the input (Symfony: "Aborted."). Twice Ctrl+C within 1.5 s stops the command (its PHP is started again: what it did not save is lost). Hidden answers are not hidden there (nostty). - Full-screen screens (symfony/tui):
JUMPHP_WEB_TERMINAL=1says the app runs there;WindowsTerminal::create()then givessrc/Ui/WebTerminal.php(raw keys and the size through the page's/dev/jumphp-termand/dev/jumphp-keys) and installssrc/Ui/WebLoop.php, a Revolt event loop without fibers (the browser's PHP has none: Revolt's own drivers abort there).stream_isatty()stays false: checkWebTerminal::available()too (the skeleton'suicommand does). Apps made before: copyWebTerminal.php,WebLoop.phpand thecreate()/UiCommandlines. - A browser that cannot isolate the page in a frame (no Document-Isolation-Policy) shows a link to open it in a tab of its own; there questions end at once and screens show their plain fallback, as before.
One executable
bin/jumphp export:standalone <app> (--linux, --windows, --macos): StaticPHP's micro of the desktop apps
(no SDL: tools/app-extensions.txt) + the app as a PHAR, booted by App\Main (dist/standalone/<app>-linux-x86_64,
<app>-windows-x86_64.exe, <app>-macos-arm64 / -x86_64). On Windows it stays a console program (games are
GUI programs: no console window). bin/jumphp installer <app> makes installers of it as for a game (no shortcut: a console program, put on the PATH instead: typed by its name in a new terminal; macOS: the installer installs the executable of the Mac, {arch}).
Windows: the commands work in any console, and so do the full-screen screens: symfony/tui's own terminal needs stty
(raw keys, the size), so the skeleton's src/Ui/WindowsTerminal.php (WindowsTerminal::create()) talks to the console
through FFI instead (raw mode with VT input, its key and resize events, the window's size, UTF-8). Tried for real on
GitHub's Windows (.github/workflows/cli-windows.yml: keys typed into hello-cli's screen). Apps made before: copy that
file and give WindowsTerminal::create() to new Tui(terminal: ...).