- Files / folders dropped from the file manager on the remote list (or a remote folder row) are uploaded there: the Tauri
runtime now tells the page every drag step at once (jumphp.on('native:drag', {phase, paths, x, y})), Window 'drop' gets x / y.
- Remote rows dragged out of the window are downloaded first to <temp>/jumphp-ssh-drag/<key>/ (ssh.stage, a key per server,
path, size, date), then a native drag hands them over: new runtime command drag.start (Linux: GTK, X11 / Wayland;
Windows / macOS: the drag crate), Window::dragFiles(), native.dragFiles.
- Remote rows dropped on a folder of the Project view are downloaded into it.
- A name already in the target: overwrite / skip / rename ("name (2).ext"), asked (ssh.conflicts, SshTransfers).
- Tests: SshDragDropTest (stand-in ssh / scp), AppTest (drop + drag.start); docs/ide.md, docs/tauri.md.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01JkYTqsvYu6AYr9yQ3Q4Nt6
663 lines
41 KiB
Markdown
663 lines
41 KiB
Markdown
# Desktop apps (Tauri): HTML pages, PHP behind them
|
|
|
|
[Français](tauri.fr.md)
|
|
|
|
JumPHP makes games (SDL: desktop, browser, phones) and **desktop applications**: native windows whose
|
|
content is **HTML / CSS / JavaScript**, shown by the system's own WebView, and whose logic is **PHP**. The window,
|
|
the WebView, the dialogs and the notifications come from [Tauri 2](https://tauri.app); the program is PHP.
|
|
|
|
```bash
|
|
bin/jumphp app:new notes "Notes" # apps/notes from skeleton-app/
|
|
bin/jumphp install notes
|
|
bin/jumphp app:run notes # a window on your screen
|
|
bin/jumphp app:test notes # php -l + phpstan + phpunit (no window) + the app on a virtual screen
|
|
bin/jumphp app:shot notes # apps/notes/var/screenshots/app.png
|
|
bin/jumphp app:export notes # apps/notes/dist/standalone/notes-linux-x86_64: one file to give
|
|
```
|
|
|
|
The example: [`games/hello-desktop`](../games/hello-desktop) (a notepad: open / save with the system's dialogs, a
|
|
PHP clock pushed to the page, files dropped on the window, a question before quitting with unsaved text).
|
|
|
|
**Native only.** Desktop apps do not run in the browser (there is no PHP-to-WebView bridge there, and a web page
|
|
is already HTML). Linux, Windows and macOS: the runtime is built and tried on the three by GitHub Actions
|
|
([Platforms](#platforms)); the one-file export is made for Linux and Windows. A **game** can use all of it too:
|
|
[hybrid games](#hybrid-games-sdl--tauri) (`ui: hybrid`).
|
|
**Nothing changes for games**: SDL games on the desktop, in the browser (WebAssembly), as standalone executables,
|
|
Android and Apple apps work exactly as before; none of their code, images or commands use any of this.
|
|
|
|
---
|
|
|
|
## How it works
|
|
|
|
PHP is the program, as in a game. Tauri is a *platform backend* that PHP drives:
|
|
|
|
```
|
|
PHP main thread (the php process) libjumphp_tauri.so (Rust, tauri/)
|
|
───────────────────────────────── ─────────────────────────────────
|
|
app.php -> App::boot() -> App::run()
|
|
└── FFI: jt_run(config, frame) ─────────────────────▶ builds the Tauri app, runs the native
|
|
event loop ON THIS THREAD (GTK on Linux)
|
|
│ every frame (60/s, and at once
|
|
App::frame() ◀──────────────────── frame() ────────────────────────┘ when something happens)
|
|
├── jt_poll(): events (JSON) ─▶ dispatch: ready, invoke, page, window, dialog, exit-requested
|
|
├── tasks, HTTP, $app->on('frame')
|
|
├── one turn of the ReactPHP loop (timers, streams)
|
|
└── jt_send(command JSON)... ─────────────────────────▶ run on the main thread after the frame:
|
|
window.*, webview.*, dialog.*, notification.*...
|
|
jt_run() returns the exit code ◀────────────────────────── when PHP sent app.exit
|
|
```
|
|
|
|
- **The same model as the browser engine**: there, the page calls `jumphp_frame()` at every
|
|
`requestAnimationFrame`; here Tauri calls PHP's `frame()` at every tick. PHP never blocks: dialogs, file choosers,
|
|
page calls answer later (a `Task`, a JavaScript `Promise`).
|
|
- **PHP decides**: closing a window or the app is an *event* PHP answers. Its default handlers close / quit;
|
|
a listener can `preventDefault()` (ask "save first?").
|
|
- **ReactPHP** stays the app's loop for timers, streams and libraries: one turn per frame (`GameLoop::start(1)`),
|
|
any loop implementation (`Loop::get()`).
|
|
- **One library for every app**: the pages are served from the app's folder at run time (`tauri://localhost/`,
|
|
through a custom Tauri `Assets`), not compiled into the library. `bin/jumphp tauri:build` builds it once.
|
|
- **FFI**: PHP loads the library with `FFI::cdef()` (4 C functions, [`tauri/include/jumphp_tauri.h`](../tauri/include/jumphp_tauri.h)).
|
|
The development image (`jumphp/tauri`) has PHP's FFI; exported apps carry a PHP built with it.
|
|
|
|
### The C API (tauri/src/lib.rs)
|
|
|
|
| Function | |
|
|
|---|---|
|
|
| `int jt_run(const char *config_json, void (*frame)(void))` | runs the app until `app.exit`; returns the exit code (negative: could not start). Once per process. |
|
|
| `const char *jt_poll(void)` | the events since the last call, a JSON array (valid until the next call) |
|
|
| `void jt_send(const char *command_json)` | one command `{"cmd": "...", ...}`, run on the main thread after the current frame |
|
|
| `const char *jt_version(void)` | the runtime's version |
|
|
|
|
Config of `jt_run`: `identifier`, `product_name`, `version`, `root` (the pages' folder), `tick_hz`.
|
|
|
|
Events: `ready`, `resumed`, `invoke {id, window, name, payload}`, `page {window, name, payload}`,
|
|
`window {window, event: close-requested | destroyed | focus | blur | resized {width, height} | moved {x, y} | drop {paths, x, y}}`,
|
|
`dialog {id, result}`, `result {id, result | error}` (the answer of a command PHP waits for; a command with an `id`
|
|
that fails answers `error` there), `tray {tray, event: menu {item} | click {button}}`, `menu {window, item, checked}` (window `*`: the app's menu),
|
|
`shortcut {accelerator, state: pressed | released}`, `exit-requested`, `error {cmd, message}`.
|
|
|
|
Commands: `window.create {window, url, title, width, height, min_width, min_height, x, y, center, resizable,
|
|
fullscreen, maximized, decorations, always_on_top, visible, devtools, icon, data_directory}`, `window.set_title`,
|
|
`window.set_size`, `window.set_position`, `window.center`, `window.set_zoom {scale}` (the page's own zoom, with `id`: a result), `window.set_fullscreen`, `window.set_resizable`,
|
|
`window.set_always_on_top`, `window.show` / `hide` / `focus` / `maximize` / `unmaximize` / `minimize` / `close`,
|
|
`window.navigate {url}`, `webview.eval {js}`, `webview.emit {name, payload}` (no `window`: all),
|
|
`invoke.resolve {window, id, ok, result}`, `dialog.message` / `dialog.confirm {id, message, title, kind, ok, cancel}`,
|
|
`dialog.open {id, title, directory, filters, multiple, folder}`, `dialog.save {id, title, directory, file_name, filters}`,
|
|
`notification.show {title, body}`, `opener.url {url}`, `opener.path {path}`, `opener.reveal {path}`,
|
|
`clipboard.write {text}`, `clipboard.read {id}`, `tray.create {tray, icon, tooltip, title, menu: [{id, text, enabled} |
|
|
{separator}], menu_on_left_click}`, `tray.set_tooltip {tray, tooltip}`, `tray.set_icon {tray, icon}`, `tray.set_menu {tray, menu: [...]}`, `tray.remove {tray}`,
|
|
`menu.set {window, menu: [{id, text, accelerator, enabled, checked} | {separator} | {role, text} | {text, items}]}`
|
|
(window `*` or none: the application's menu), `menu.remove {window}`, `menu.set_item {window, item, enabled, checked, text}`,
|
|
`shortcut.register {accelerator}`, `shortcut.unregister {accelerator}`, `shortcut.unregister_all`,
|
|
`drag.start {id, window, paths, icon}` (a native drag of local files out of the window; `result`: `dropped` / `cancelled`),
|
|
`app.emit {name, payload}` (Tauri events, for pages using `@tauri-apps/api`), `app.tick {hz}`, `app.exit {code}`.
|
|
|
|
You never need them directly: `JumPHP\Tauri\App` and `Window` send them.
|
|
|
|
---
|
|
|
|
## An app
|
|
|
|
```
|
|
apps/notes/
|
|
app.php exit(JumPHP\Tauri\App::boot(__DIR__)->run());
|
|
composer.json requires jumphp/engine, autoload App\ -> src/
|
|
config/project.yaml ui: webview, main: App\Main, app: {...}
|
|
src/Main.php implements JumPHP\Tauri\AppMain: commands, listeners, timers
|
|
ui/ the pages: index.html, CSS, JS, pictures (any front-end tool's build output works too)
|
|
assets/icon.png the window's icon
|
|
tests/MainTest.php extends JumPHP\Testing\AppTestCase
|
|
var/ the user's files when run from the project (exported apps: ~/.local/share/<id>)
|
|
```
|
|
|
|
### config/project.yaml
|
|
|
|
```yaml
|
|
project:
|
|
id: notes # identifier net.jumphp.notes, data folder, executable name
|
|
title: "Notes" # window title, product name
|
|
version: 0.1.0
|
|
lang: en
|
|
ui: webview # a desktop app: bin/jumphp app:* (run / test / shot hand over to them)
|
|
main: App\Main # made with new, then boot(App $app) once before the window opens
|
|
app:
|
|
identifier: com.example.notes # default net.jumphp.<id without dashes>
|
|
pages: ui # the pages' folder (default ui)
|
|
tick_hz: 60 # frames a second when nothing happens
|
|
icon: assets/icon.png # default: assets/icon.png when it exists
|
|
native_commands: true # the built-in native.* commands for pages (below)
|
|
smoke_page: true # app:test fails when the main page never loads
|
|
autostart: {default: false, hidden: true} # starting with the computer (below): on at the first start?
|
|
# started at login, the main window hidden (a tray app)? `autostart: true` = default on
|
|
window: # the main window: every window.create option
|
|
url: index.html
|
|
width: 960
|
|
height: 640
|
|
min_width: 480
|
|
min_height: 320
|
|
resizable: true
|
|
devtools: false # true: the WebView inspector opens with it
|
|
```
|
|
|
|
### The PHP side
|
|
|
|
```php
|
|
namespace App;
|
|
|
|
use JumPHP\Native\Dialog;
|
|
use JumPHP\Native\FilePicker;
|
|
use JumPHP\Tauri\App;
|
|
use JumPHP\Tauri\AppMain;
|
|
use JumPHP\Tauri\NativeEvent;
|
|
|
|
final class Main implements AppMain
|
|
{
|
|
public function boot(App $app): void
|
|
{
|
|
// page -> PHP -> page: const r = await jumphp.invoke('greet', {name: 'Ada'})
|
|
$app->command('greet', fn (array $p) => "Hello {$p['name']}");
|
|
|
|
// an answer that comes later: return a Task
|
|
$app->command('pick', fn () => FilePicker::open(['filters' => ['Text' => ['txt', 'md']]]));
|
|
|
|
// PHP -> page: jumphp.on('clock', ...)
|
|
$app->gameLoop->addPeriodicTimer(1.0, fn () => $app->send('clock', ['time' => date('H:i:s')]));
|
|
|
|
// page -> PHP without an answer: jumphp.send('clicked', {...})
|
|
$app->on('page:clicked', fn (mixed $payload, string $window) => null);
|
|
|
|
// PHP decides what closing does
|
|
$app->window()->on('close-requested', function (NativeEvent $e) use ($app) {
|
|
$e->preventDefault();
|
|
Dialog::confirm('Quit?', 'Notes', 'Quit', 'Stay')->then(fn ($yes) => $yes && $app->quit());
|
|
});
|
|
}
|
|
}
|
|
```
|
|
|
|
`JumPHP\Tauri\App`:
|
|
|
|
| | |
|
|
|---|---|
|
|
| `App::boot($root, ?NativeRuntime $runtime = null)` | config, runtime (FFI), main window, `main` class |
|
|
| `run(): int` | runs until the app quits; the exit code |
|
|
| `command($name, fn (mixed $payload, Invocation $call) => mixed)` | what pages call; a returned `Task` answers when it ends; an exception rejects the page's promise with its message |
|
|
| `send($name, $payload)` | to every page (`jumphp.on`) |
|
|
| `window($label = 'main')`, `windows()`, `createWindow($label, $options)` | windows |
|
|
| `on('ready' \| 'frame' \| 'loaded' \| 'exit-requested' \| 'page:<name>' \| 'error' \| 'quit' \| 'native', ...)` | events |
|
|
| `quit($code = 0)` | closes everything after this frame |
|
|
| `gameLoop`, `storage`, `options`, `lang`, `config`, `tasks()`, `http()` | as in games (`Storage`, `Options`, `Lang`, `Tasks`, `Http`) |
|
|
| `time()`, `frameCount()`, `setTickRate($hz)`, `pagesDir()`, `isSmoke()` | |
|
|
| `App::current()` | the running app (for code without access to it) |
|
|
|
|
`JumPHP\Tauri\Window`: `setTitle()`, `setSize()`, `setPosition()`, `center()`, `setFullscreen()`, `setResizable()`,
|
|
`setAlwaysOnTop()`, `setZoom($scale)` (Task: the page's zoom like a browser's Ctrl + / -, 1 = 100 %), `show()`, `hide()`, `focus()`, `maximize()`, `unmaximize()`, `minimize()`, `close()`,
|
|
`navigate($url)`, `eval($js)`, `send($name, $payload)`, `isOpen()`, `isLoaded()`, `geometry()`; events
|
|
`close-requested` (NativeEvent), `closed`, `focus`, `blur`, `resized` (w, h), `moved` (x, y), `drop` (paths, x, y),
|
|
`loaded`. `dragFiles($paths, $icon = null)` (Task): a native drag of local files out of the window (below).
|
|
|
|
### Drag and drop with the system's file manager
|
|
|
|
- **Into the window**: files and folders dropped from the file manager (Nautilus, Dolphin, Explorer, Finder) come with their
|
|
real paths (a page's `File` objects have none). PHP gets `$window->on('drop', fn (array $paths, float $x, float $y) => ...)`;
|
|
the page gets every step at once, without waiting for a frame (the hover too):
|
|
`jumphp.on('native:drag', ({phase, paths, x, y}) => ...)`, `phase` = `enter` (with `paths`) / `over` / `drop` (with `paths`) /
|
|
`leave`, `x` / `y` in the window's logical pixels (CSS pixels at zoom 1: divide by the page's own zoom; WebKitGTK also gives
|
|
the page its own `dragover` events with `Files`, in CSS pixels). The page's own HTML5 `drop` of files does not happen in the
|
|
desktop app (the runtime takes it); drags inside the page (`draggable`) work as usual.
|
|
- **Out of the window**: HTML5 drag and drop cannot give the file manager a file (WebKitGTK ignores `DownloadURL`). A page
|
|
asks for a native drag while its mouse button is still down (on `mousemove` past a few pixels, or when the pointer leaves the
|
|
window): `await jumphp.invoke('native.dragFiles', {paths: ['/tmp/report.pdf']})` (or `$window->dragFiles([...])` in PHP) →
|
|
`'dropped'` / `'cancelled'`; it fails when the system refuses to start a drag (the button was already released). The files must
|
|
exist first (download remote ones to a temporary folder before). Linux: GTK's own drag (`text/uri-list`, X11 and Wayland);
|
|
Windows: OLE `DoDragDrop`; macOS: an `NSDraggingSession` (the `drag` crate; built by the `tauri` workflow, not tried on a Mac
|
|
yet). No lazy "file promises" yet: the files are complete before the drag begins. An older runtime library answers
|
|
`unknown command 'drag.start'`: offer a download dialog then. Example: the IDE's SSH window (`ide/ui/js/ssh.js`).
|
|
|
|
### The page side: `window.jumphp`
|
|
|
|
Injected in every page before its own scripts (it is there in `<script>` tags and modules alike):
|
|
|
|
```js
|
|
const r = await jumphp.invoke('greet', {name: 'Ada'}); // a Promise: resolves with PHP's answer, rejects with its exception's message
|
|
jumphp.send('clicked', {x: 1}); // PHP: $app->on('page:clicked', ...)
|
|
const off = jumphp.on('clock', (p) => ...); // PHP: $app->send('clock', ...) / $window->send(...)
|
|
jumphp.native; // true: running in a desktop app
|
|
```
|
|
|
|
The pages are ordinary web pages: any CSS, any framework, a bundler's output in `ui/` (`app.pages` can point at
|
|
`dist/`). They are served from `tauri://localhost/` (a request for a folder serves its `index.html`); never from
|
|
outside the pages' folder. A window can also show an `https://` page (`url`), without `window.jumphp`.
|
|
|
|
### Built-in native commands
|
|
|
|
Without PHP code of its own, a page can ask (they go through PHP, `JumPHP\Tauri\NativeCommands`; project.yaml
|
|
`app.native_commands: false` removes them):
|
|
|
|
```js
|
|
await jumphp.invoke('native.message', {message: 'Saved', title: 'Notes', kind: 'info'}); // info | warning | error
|
|
const yes = await jumphp.invoke('native.confirm', {message: 'Delete?', ok: 'Delete', cancel: 'Keep'});
|
|
const file = await jumphp.invoke('native.open', {filters: {Images: ['png', 'jpg']}}); // null: cancelled
|
|
const files = await jumphp.invoke('native.open', {multiple: true});
|
|
const dir = await jumphp.invoke('native.open', {folder: true});
|
|
const out = await jumphp.invoke('native.save', {file_name: 'notes.txt'});
|
|
await jumphp.invoke('native.notify', {title: 'Done', body: 'Export finished'});
|
|
await jumphp.invoke('native.openUrl', {url: 'https://jumphp.net'});
|
|
await jumphp.invoke('native.dragFiles', {paths: ['/tmp/a.txt']}); // the mouse still down: a native drag out ('dropped' / 'cancelled')
|
|
const s = await jumphp.invoke('native.autostart'); // {supported, enabled, atLogin}
|
|
await jumphp.invoke('native.autostart', {on: true}); // starts with the computer (below)
|
|
```
|
|
|
|
### Starting with the computer
|
|
|
|
An exported app can start when the user logs in (no administrator rights; `JumPHP\Native\Autostart`):
|
|
|
|
```php
|
|
$start = $app->autostart();
|
|
if ($start->isSupported()) { // an exported app on Windows, macOS or Linux (not `php app.php`)
|
|
$start->set(true); // or false; isEnabled() reads what the system has
|
|
}
|
|
$start->startedAtLogin(); // true when the computer started it (the --autostart flag)
|
|
```
|
|
|
|
- Windows: the value `<id>` of `HKCU\Software\Microsoft\Windows\CurrentVersion\Run` (`"<exe>" --autostart`);
|
|
- macOS: `~/Library/LaunchAgents/<identifier>.plist` (RunAtLoad) that runs `open -a <the .app> --args --autostart`;
|
|
- Linux: `~/.config/autostart/<id>.desktop` (GNOME, KDE, Xfce...).
|
|
|
|
project.yaml `app.autostart`: `default: true` turns it on at the first start of the exported app (once: then the user
|
|
decides, e.g. a check box of the app's menu or settings); `hidden: true` starts the main window hidden when the
|
|
computer started it, for an app that lives in the tray (`$app->tray()`: its menu shows the window). A page asks with
|
|
`native.autostart`. `games/hello-desktop` has View > Start with the computer.
|
|
|
|
The installers (`bin/jumphp installer <app>`, jumphp2installer 0.2.9+) show a box "Start <App> with the computer" when
|
|
project.yaml has `app: {autostart: ...}`, ticked from its `default`. They write the same entry as `$app->autostart()`, the
|
|
uninstaller takes it out, and the app's own first start leaves that choice alone (the installer's `.jumphp-autostart`
|
|
file beside the executable).
|
|
|
|
### The command line (no window): `AppCli`
|
|
|
|
A main class that also implements `JumPHP\Tauri\AppCli` gets `static cli(array $args, string $root): ?int` first,
|
|
before the native library is loaded: return an exit code to stop there (`--help`, `--version`, a silent install), or
|
|
`null` to open the window as usual. Blocking is allowed there (no frame runs yet).
|
|
|
|
```php
|
|
final class Main implements AppMain, AppCli
|
|
{
|
|
public static function cli(array $args, string $root): ?int
|
|
{
|
|
if (in_array('--version', $args, true)) {
|
|
echo "1.0\n";
|
|
return 0;
|
|
}
|
|
return null;
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Native features from PHP: `JumPHP\Native`
|
|
|
|
The same calls on every target; who does them depends on where the code runs:
|
|
|
|
```php
|
|
use JumPHP\Native\{Dialog, FilePicker, Notification, Shell, Native};
|
|
|
|
Dialog::message('Saved.', 'Notes'); // Task: true once closed
|
|
Dialog::confirm('Delete?', 'Notes', 'Delete', 'Keep')->then(fn (bool $yes) => ...);
|
|
FilePicker::open(['filters' => ['Text' => ['txt']]])->then(fn (?string $file) => ...);
|
|
FilePicker::open(['multiple' => true])->then(fn (?array $files) => ...);
|
|
FilePicker::folder()->then(fn (?string $dir) => ...);
|
|
FilePicker::save(['file_name' => 'out.txt'])->then(fn (?string $file) => ...);
|
|
Notification::show('Done', 'Export finished'); // bool
|
|
Shell::openUrl('https://jumphp.net'); Shell::openPath($file); Shell::reveal($file);
|
|
Clipboard::copy('text'); Clipboard::paste()->then(fn (string $text) => ...);
|
|
Native::supports('open'); Native::name(); // 'tauri', 'sdl', 'browser', 'none'
|
|
```
|
|
|
|
| Target | `Native::name()` | Features |
|
|
|---|---|---|
|
|
| desktop app (`JumPHP\Tauri\App`), hybrid game | `tauri` | all: message, confirm, open, save, folder, notify, openUrl, openPath, reveal, copy, paste |
|
|
| SDL game on the desktop | `sdl` | message (SDL's own message box, modal) |
|
|
| browser build | `browser` | openUrl (a new tab), copy |
|
|
| headless runs (`test`, `shot`), elsewhere | `none` | nothing |
|
|
|
|
What a target lacks fails the Task with `JumPHP\Native\UnsupportedFeature` (or returns `false`): check
|
|
`Native::supports()` first. `Native::setProvider()` puts another one (tests, a custom provider implementing
|
|
`JumPHP\Native\Provider`). Dialogs never block the frame (answers come back as Tasks), except SDL's message box,
|
|
which is modal by nature.
|
|
|
|
Desktop apps and hybrid games also have, through `App` (`App::current()` from anywhere):
|
|
|
|
```php
|
|
// an icon in the system's tray, with a menu (Linux: libayatana-appindicator3 and a desktop that shows tray icons;
|
|
// the click event is not sent on Linux, the menu is)
|
|
$app->tray('main', ['tooltip' => 'Notes', 'menu' => [['id' => 'show', 'text' => 'Show'], '-', ['id' => 'quit', 'text' => 'Quit']]])
|
|
->on('menu', fn (string $item) => $item === 'quit' ? $app->quit() : $app->window()->show()->focus());
|
|
|
|
// a shortcut of the whole system, even without the focus (Linux: X11, not Wayland)
|
|
$app->globalShortcut('CmdOrCtrl+Shift+K', fn () => $app->window()->show()->focus());
|
|
|
|
// menus (JumPHP\Tauri\Menu): a window's ($app->window()->setMenu()) or the whole app's ($app->setMenu());
|
|
// items with an id (and an accelerator), check items ('checked'), separators ('-'), submenus ('items') and the
|
|
// system's own items ('role': quit about copy cut paste select_all undo redo minimize maximize fullscreen hide
|
|
// hide_others show_all close_window services). On macOS there is one menu bar: a window's menu becomes the app's.
|
|
$app->window()->setMenu([
|
|
['text' => 'File', 'items' => [['id' => 'open', 'text' => 'Open...', 'accelerator' => 'CmdOrCtrl+O'], '-', ['role' => 'quit']]],
|
|
['text' => 'View', 'items' => [['id' => 'wrap', 'text' => 'Wrap lines', 'checked' => true]]],
|
|
]);
|
|
$app->window()->on('menu', fn (string $item, ?bool $checked) => ...); // also $app->on('menu', fn ($item, $window, $checked))
|
|
$app->window()->setMenuItem('wrap', ['checked' => false, 'enabled' => true, 'text' => 'Wrap']);
|
|
```
|
|
|
|
Lower levels stay available: PHP's **FFI** for any C library of the system (the desktop app's PHP has it), and
|
|
PHP extensions.
|
|
|
|
---
|
|
|
|
## Hybrid games (SDL + Tauri)
|
|
|
|
A game can drive Tauri too: `ui: hybrid` in its `config/project.yaml`. It stays an SDL game (scenes, entities, its
|
|
SDL window, sound; `app.php` unchanged), and gets the desktop apps' native side: `JumPHP\Native` (file choosers,
|
|
dialogs, notifications, clipboard), a tray icon, global shortcuts, and HTML windows beside its own (a control
|
|
panel, an editor, a launcher...). Example: [`games/hello-hybrid`](../games/hello-hybrid) (balls bouncing in SDL, an
|
|
HTML control panel, "save a picture" through the system's file chooser, a tray menu, Ctrl+Shift+P anywhere).
|
|
|
|
```yaml
|
|
project:
|
|
start_scene: App\Scene\BallsScene
|
|
ui: hybrid
|
|
main: App\Desktop # optional: an AppMain (commands for the HTML windows, tray icon, shortcuts)
|
|
app:
|
|
window: {url: index.html, width: 340, height: 560} # optional: an HTML window (pages in ui/)
|
|
```
|
|
|
|
How: `Application::run()` hands over to `JumPHP\Tauri\Hybrid`: the Tauri runtime runs the main thread's loop and
|
|
calls the app's frame, which runs one turn of ReactPHP, where the game's frame timer ticks the engine as usual.
|
|
The runtime leaves the loop some idle time after each frame, so the WebViews keep painting while the game runs.
|
|
The game quits when its SDL window closes (closing the HTML window does not end it); `Engine::quit()` ends both.
|
|
|
|
The scenes use the native side when it is there and work without it:
|
|
|
|
```php
|
|
if (Native::supports('save')) {
|
|
FilePicker::save(['file_name' => 'picture.png'])->then(fn (?string $f) => $f && $this->engine->sdl->saveScreenshot($f));
|
|
}
|
|
App::current()?->send('stats', ['score' => $this->score]); // to the HTML window(s), when there is a native side
|
|
```
|
|
|
|
It runs as a **plain game** (no Tauri) in headless runs (`bin/jumphp test` / `shot`: game tests work as before), in
|
|
the browser, in the phone apps, and on a desktop without FFI or without the runtime (a line on stderr says so).
|
|
`bin/jumphp run <game>` runs a hybrid game in the Tauri image; `export:standalone <game>` makes it with a micro that
|
|
has SDL **and** FFI (`tools/hybrid-extensions.txt`, built once) and the runtime library inside. Test the native
|
|
side with `AppTestCase` (it boots the `main` class and the `app.window` of project.yaml), the game with `GameTestCase`.
|
|
|
|
### One window: the game inside the Tauri window
|
|
|
|
`app: {embed: true}` puts the game **in** the Tauri window instead of a window of SDL's own
|
|
(`JumPHP\Tauri\EmbeddedGame`):
|
|
|
|
```yaml
|
|
project:
|
|
ui: hybrid
|
|
app:
|
|
embed: true
|
|
window: {width: 960, height: 540} # optional: the window (default: width x height x scale; no url)
|
|
```
|
|
|
|
SDL draws each frame into memory (its software renderer, as headless shots; no SDL window, video driver `dummy`);
|
|
the picture (a BMP, ~0.2 ms for 320 x 180) goes to the runtime through `jt_frame()` and JumPHP's page
|
|
(`engine/web/tauri/game.html`, served as `/__jumphp/game.html`) draws the newest one on a canvas, sharp and
|
|
letterboxed (`integer_scale` honoured), once per screen refresh. The keyboard, the mouse (in the game's pixels) and
|
|
the focus come back through `jumphp.send('__input')` into the engine's `InputManager`: actions, F3 and F11
|
|
(fullscreen of the Tauri window) work as usual; gamepads are read by SDL. Closing the window ends the game. Sound
|
|
stays SDL's. Other HTML windows: `$app->createWindow()` in the `main` class. Tried for real with Pong on Xvfb (the
|
|
menu, then Enter from the page started a game). Without what it needs (headless, browser, phones, no FFI), the game
|
|
keeps its SDL window. For bigger resolutions or OpenGL games, a window of SDL's own stays the better choice (the
|
|
picture is copied once per frame, and GL is not drawn into memory).
|
|
|
|
---
|
|
|
|
## Tests
|
|
|
|
`JumPHP\Testing\AppTestCase` plays the app **without a window** (a `FakeRuntime`: no FFI, no GTK, runs anywhere):
|
|
the test is the page and the user.
|
|
|
|
```php
|
|
final class MainTest extends AppTestCase
|
|
{
|
|
public function testThePageIsGreeted(): void
|
|
{
|
|
self::assertSame('Hello Ada', $this->invoke('greet', ['name' => 'Ada']));
|
|
}
|
|
|
|
public function testClosingAsks(): void
|
|
{
|
|
$this->requestClose(); // the user clicks the window's close button
|
|
self::assertSame([], $this->sent('window.close'));
|
|
$this->answerDialog(true); // and answers the dialog PHP opened
|
|
self::assertNotNull($this->lastSent('app.exit'));
|
|
}
|
|
}
|
|
```
|
|
|
|
`invoke($name, $payload)` (the answer; a rejection throws), `pageSend($name, $payload)`, `pageLoaded()`,
|
|
`requestClose()`, `answerDialog($answer)`, `frames($n)`, `wait($seconds)` (real time: ReactPHP timers),
|
|
`sent($cmd)`, `lastSent($cmd)`, `$this->runtime->push($event)` (any native event), `$this->app`.
|
|
|
|
`bin/jumphp app:test <app>` runs them, then **the app for real** on a virtual screen (Xvfb, WebKitGTK, the
|
|
library): it fails on a PHP warning, an exception, or when the main page never loaded (`JUMPHP_MAX_FRAMES`,
|
|
default 240). `bin/jumphp app:shot <app> [frames] [out.png]` saves the main window's picture.
|
|
|
|
---
|
|
|
|
## Exporting: one executable
|
|
|
|
`bin/jumphp app:export <app>` makes `apps/<app>/dist/standalone/<app>-linux-x86_64`: one file, nothing to
|
|
install but WebKitGTK (as every Tauri app on Linux); `--windows` makes `<app>-windows-x86_64.exe` (Windows 10 / 11
|
|
have WebView2; its micro and library come from JumPHP's GitHub releases, see [Platforms](#platforms)). It reuses
|
|
`export:standalone` ([standalone.md](standalone.md)):
|
|
|
|
| Part | |
|
|
|---|---|
|
|
| PHP | StaticPHP's micro with `tools/app-extensions.txt` (FFI, OpenSSL, mbstring, sockets, pcntl...; no SDL): its own micro, built once in `~/.jumphp/standalone/spc-app` (~10 min), kept |
|
|
| php.ini | `ffi.enable=1`, injected in the executable (micro's ini section) |
|
|
| the app | `apps/<app>` + its vendor/, as a PHAR, unpacked on the first launch into `~/.cache/jumphp/<id>-<build>` |
|
|
| the runtime | `build/tauri/linux-x86_64/libjumphp_tauri.so`, unpacked with it into `native/linux-x86_64/` |
|
|
| the user's files | `~/.local/share/<id>` (saves, options, the WebView's storage in `webview/`) |
|
|
|
|
The computer needs **WebKitGTK 4.1** (`libwebkit2gtk-4.1-0`: Debian 12+, Ubuntu 22.04+, Fedora 39+, Arch
|
|
`webkit2gtk-4.1`) and glibc 2.34 or newer. **When it is missing, the app offers to install it** before opening
|
|
any window (`JumPHP\Tauri\LinuxWebView`): it finds the distribution (`/etc/os-release`), asks (in the terminal it
|
|
was started from, else a `zenity` / `kdialog` dialog), installs the package with the user's rights (root,
|
|
`pkexec`'s password window, or `sudo` in the terminal), then starts. Declined or impossible (no password, no
|
|
network, an immutable system, an unknown distribution): it shows the exact command to run and stops.
|
|
`JUMPHP_INSTALL=yes` installs without asking (scripts), `no` only says what to do. Tried on bare Debian 13,
|
|
Ubuntu 24.04, Fedora 42 and Arch (each installed its package, then the app opened its window), and declining in
|
|
a terminal.
|
|
|
|
The game export is untouched: without the apps' variables, `export:standalone` builds and finds the same micro as
|
|
before (same key).
|
|
|
|
### macOS: an .app
|
|
|
|
`bin/jumphp app:export <app> --macos` (from Linux, in Docker) makes `dist/standalone/<app>-macos.zip`: `<Title>.app`
|
|
with two executables (Apple silicon, Intel: micro + the app), a launcher that starts the Mac's own, `Info.plist`
|
|
(project.yaml `title`, `version`, `app.identifier`) and the icon (`assets/icon.png` as `.icns`); the universal library
|
|
inside. macOS 12 or newer. The app's cache and data go to `~/Library/Caches/JumPHP` and
|
|
`~/Library/Application Support/<id>`. It is not signed (Apple's developer account): the first time, right click on
|
|
the app > Open. The workflow `app-export` (Actions > app-export) exports an app and opens it for real on an Apple
|
|
silicon Mac and an Intel Mac (and on Ubuntu), then makes its **.dmg** (`hdiutil` only exists on a Mac): the
|
|
artifact `dmg` of the run, `<app>-macos.dmg` (the .app and a link to Applications to drag it onto).
|
|
|
|
## In the browser, on phones
|
|
|
|
The same app also runs in a web page: `bin/jumphp build <app>` makes `dist/web/` (static files, like a game's),
|
|
`bin/jumphp serve <app>` / `webshot <app>` try it. Its pages are the same files (copied to `app/`, each with
|
|
`jumphp-app-frame.js` first: the same `window.jumphp`); its PHP runs in JumPHP's WebAssembly engine
|
|
(`JumPHP\Tauri\BrowserRuntime`, `engine/bootstrap/wasm.php` starts an `App` for `ui: webview`), and
|
|
`engine/web/jumphp-app.js` does in HTML what Tauri does on the desktop:
|
|
|
|
| On the desktop | In the browser |
|
|
|---|---|
|
|
| windows | the main one fills the page; the others float over it (title bar, drag, close) |
|
|
| menus, their shortcuts, check items | a menu bar at the top (roles copy / paste / undo... act on the page) |
|
|
| `Dialog::message()` / `confirm()` | an HTML dialog |
|
|
| `FilePicker::open()` / `folder()` | the browser's file picker; the files are copied into PHP's `/tmp/open/` (their paths come back) |
|
|
| `FilePicker::save()` | a path in `/tmp/save/`: what PHP writes there is downloaded right after |
|
|
| `Notification::show()` | the Notification API (else a message in the corner) |
|
|
| `Shell::openUrl()`, `Clipboard` | a new tab, `navigator.clipboard` |
|
|
| files dropped on a page | copied into `/tmp/drop/` |
|
|
| tray icon, system-wide shortcuts, opening paths | nothing (shortcuts work while the page has the focus) |
|
|
|
|
The app's own files (`$app->storage`, options) live in the browser (IndexedDB), as games' saves. Phones: the page
|
|
works there as it is; as an Android app, `bin/jumphp twa <app> --url <its page online>` (project.yaml `pwa: true`); on an
|
|
iPhone, Safari's "Add to Home Screen" (PWA). Tried in headless Chrome with `games/hello-desktop`: the greeting from
|
|
PHP, the View menu's check item, the confirm dialog, "Save as" downloading the note PHP wrote, no error.
|
|
**Native phone apps**: `bin/jumphp android <app>` (an `.apk` / `.aab`) and `bin/jumphp ios <app>` (an `.ipa` + the
|
|
simulator's app, built on GitHub's Macs) put this browser build inside the app, shown by the phone's own WebView
|
|
(Android `WebView`, iOS `WKWebView`) from a secure origin of its own, with no network needed. What a page can not do
|
|
goes to the phone through a small bridge that `jumphp-app.js` uses when it is there: "save" = the system's save dialog
|
|
(Android) / "save to Files" (iOS), notifications, links in the browser, sharing, the clipboard; opening files is the
|
|
page's file picker, answered by the system. Android: tried in an emulator with `games/hello-desktop` (the greeting from
|
|
PHP, "Save as" opening the system's dialog). iOS: written the same way, not tried yet. (Tauri's own mobile runtime is
|
|
not used: its loop belongs to the activity / UIKit there.)
|
|
|
|
## Updates
|
|
|
|
An exported app can update itself (`JumPHP\Tauri\Updater`, `$app->updater()`): no installer, the executable is
|
|
replaced by the newer one.
|
|
|
|
```bash
|
|
bin/jumphp app:release notes --url https://example.com/notes --notes "Faster saving." --linux --windows --macos
|
|
# then upload apps/notes/dist/standalone/ (the executables + update.json) to https://example.com/notes
|
|
```
|
|
|
|
- The first time, it makes the app's signing key (ECDSA P-256) in `~/.jumphp/keys/<id>-update.pem` (never in the
|
|
project; **keep a copy**: without it the apps already given can not be updated) and writes its public half to
|
|
`config/update.pub` (commit it: the app checks what it downloads with it).
|
|
- `update.json`: the app's id, its `version` (project.yaml: bump it for each release), the notes, and for each system
|
|
just exported (`linux-x86_64`, `windows-x86_64`, `macos-arm64`, `macos-x86_64`) the executable's address, size and
|
|
SHA-256, all signed.
|
|
- The app knows where to look: project.yaml `app: {update: {url: https://example.com/notes/update.json}}`
|
|
(`JUMPHP_UPDATE_URL` tries another one).
|
|
|
|
```php
|
|
$app->updater()->check()->then(function (?Update $update) use ($app) { // null: up to date
|
|
if ($update !== null && $app->updater()->isInstallable()) { // false under `php app.php`
|
|
Dialog::confirm("Version $update->version is out. $update->notes\nInstall it?", 'Notes', 'Install', 'Later')
|
|
->then(fn ($yes) => $yes ? $update->install()->then(fn () => $app->updater()->relaunch()) : null);
|
|
}
|
|
});
|
|
```
|
|
|
|
`check()` fails on a wrong signature or another app's file; `install()` downloads, refuses a wrong SHA-256, then
|
|
replaces the executable (Windows: the running one is renamed `*.old`, removed at the next start; macOS: the
|
|
executable of the Mac's processor inside the `.app`); `relaunch()` starts it and quits. `games/hello-desktop` has
|
|
Help > Check for updates (tried for real: 0.1.0 found 0.1.1, installed it and restarted as 0.1.1).
|
|
|
|
---
|
|
|
|
## Commands
|
|
|
|
| Command | |
|
|
|---|---|
|
|
| `app:new <app> [title]` | `apps/<app>` from `skeleton-app/` |
|
|
| `app:run <app>` | the app on your screen (X11, else Wayland; the session bus for notifications; the GPU) |
|
|
| `app:test <app>` | php -l, phpstan, phpunit, then the app for real on Xvfb |
|
|
| `app:shot <app> [frames] [out.png]` | the main window after N frames (default 120) |
|
|
| `app:export <app> [--linux] [--windows] [--macos]` | one executable for Linux (default), an `.exe` for Windows, an `.app` (zip) for macOS |
|
|
| `app:release <app> --url <base> [--notes "..."] [--linux] [--windows] [--macos]` | exported + a signed `update.json` ([Updates](#updates)) |
|
|
| `tauri:setup` | the `jumphp/tauri` image: the desktop runtime + FFI + Rust + WebKitGTK headers (~5 min) |
|
|
| `tauri:build` | `tauri/` -> `build/tauri/linux-x86_64/libjumphp_tauri.so` (~5 min the first time, Cargo caches in `~/.jumphp/tauri`) |
|
|
| `tauri:download [platform...\|--all]` | the library of these sources of `tauri/` from JumPHP's GitHub releases: `linux-x86_64` (default), `windows-x86_64`, `macos-universal` |
|
|
|
|
The app commands get the library when it is missing or older than its sources: downloaded when the release of
|
|
these sources exists, else built (`JUMPHP_TAURI_BUILD=1`: always built).
|
|
|
|
`install <app>` and `composer <app> ...` are the games' commands (composer works the same).
|
|
`run`, `test` and `shot` on an app's folder hand over to `app:run`, `app:test`, `app:shot`; `pages` skips apps
|
|
(they have no browser build).
|
|
|
|
Environment: `JUMPHP_TAURI_LIB` (another library file), `JUMPHP_TAURI_TRACE=1` (every command and event on
|
|
stderr), `JUMPHP_TAURI_IMAGE`, `JUMPHP_TAURI_BUILD`, `JUMPHP_TAURI_RELEASES`, `JUMPHP_SMOKE`, `JUMPHP_MAX_FRAMES`,
|
|
`JUMPHP_SCREENSHOT`, `JUMPHP_VAR`.
|
|
|
|
Where `TauriRuntime` looks for the library: `JUMPHP_TAURI_LIB`; `<app>/native/<platform>/libjumphp_tauri.so`
|
|
(exported apps); `build/tauri/<platform>/` going up from the app (the project); `/usr/local/lib`, `/usr/lib`.
|
|
|
|
---
|
|
|
|
## Repository
|
|
|
|
| Path | |
|
|
|---|---|
|
|
| `tauri/` | the runtime (Rust crate `jumphp-tauri`, a `cdylib`): `src/lib.rs` (C API, commands, events, assets), `src/bridge.js` (`window.jumphp`), `include/jumphp_tauri.h`, `tauri.conf.json` (a minimal config: windows are made by PHP), `Cargo.lock` |
|
|
| `engine/src/Tauri/` | `App`, `Window`, `Menu`, `Tray`, `AppMain`, `Hybrid`, `Invocation`, `NativeEvent`, `NativeCommands`, `NativeRuntime`, `TauriRuntime` (FFI), `FakeRuntime` |
|
|
| `engine/src/Native/` | `Native`, `Dialog`, `FilePicker`, `Notification`, `Shell`, `Clipboard`, providers (`TauriProvider`, `SdlProvider`, `BrowserProvider`, `NullProvider`), `UnsupportedFeature` |
|
|
| `engine/src/Testing/AppTestCase.php` | tests without a window |
|
|
| `skeleton-app/` | the app template (`app:new`) |
|
|
| `games/hello-desktop/` | the example app |
|
|
| `games/hello-hybrid/` | the example hybrid game |
|
|
| `.github/workflows/tauri.yml`, `tools/tauri-key.sh` | the libraries for Linux, Windows, macOS: built, tried, published |
|
|
| `docker/tauri/Dockerfile` | the image (FROM the desktop image: same PHP 8.5 and extensions, + FFI, Rust, WebKitGTK, Xvfb tools) |
|
|
| `tools/app-commands.sh` | the `app:*` / `tauri:*` commands (sourced by `bin/jumphp`) |
|
|
| `tools/app-extensions.txt`, `tools/hybrid-extensions.txt`, `tools/new-app.php` | the micros' extensions of apps / hybrid games, `app:new`'s renaming |
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
| Symptom | Fix |
|
|
|---|---|
|
|
| `No Tauri runtime (linux-x86_64/libjumphp_tauri.so)` | `bin/jumphp tauri:build`, or `JUMPHP_TAURI_LIB=<file>` |
|
|
| `PHP's FFI extension is missing` | run it with `bin/jumphp app:run` (the `jumphp/tauri` image), or a PHP with `--with-ffi` and `ffi.enable=1` (or `preload`, CLI) |
|
|
| `FFI API is restricted by "ffi.enable"` | `ffi.enable=1` (exported apps have it) |
|
|
| A blank window in a screenshot | taken too early: more frames (`app:shot <app> 180`) |
|
|
| `app:test`: the main page never loaded | `ui/index.html` missing (or `app.pages` / `window.url` wrong), or a JavaScript error before the page's end: open the inspector (`devtools: true`, `app:run`) |
|
|
| `jumphp.invoke()` rejects `no command 'x'` | `$app->command('x', ...)` in `AppMain::boot()` |
|
|
| The exported app does not start: `libwebkit2gtk-4.1.so.0: cannot open shared object file` | install WebKitGTK 4.1 (`sudo apt install libwebkit2gtk-4.1-0`) |
|
|
| Nothing happens on a notification | no notification daemon / session bus (inside Docker: `app:run` mounts the session bus when it exists) |
|
|
| `Overriding existing handler for signal 10` on stderr | WebKit's own message, harmless |
|
|
|
|
A PHP *fatal* error (not an exception) during a frame cannot be caught: it ends the process (as in any PHP program).
|
|
|
|
---
|
|
|
|
## Platforms
|
|
|
|
| | Linux x86_64 | Windows x86_64 | macOS (Apple silicon + Intel) |
|
|
|---|---|---|---|
|
|
| WebView | WebKitGTK 4.1 | WebView2 (Edge; the library packs Microsoft's bootstrapper and installs it silently when it is missing, e.g. a fresh Windows 10) | WKWebView |
|
|
| runtime library | `libjumphp_tauri.so` | `jumphp_tauri.dll` | `libjumphp_tauri.dylib` (universal) |
|
|
| built and tried by | `tauri:build` here, and the workflow | the workflow | the workflow |
|
|
| `app:run` / `app:test` / `app:shot` | yes (Docker) | — (run `php app.php` with PHP's FFI) | — (same) |
|
|
| one-file export | `app:export` | `app:export --windows` | `app:export --macos` (an `.app` in a zip) |
|
|
|
|
The workflow `.github/workflows/tauri.yml` (on each change of `tauri/` or of the PHP side, or by hand) builds the
|
|
library on the three systems (Ubuntu 22.04, so glibc 2.35+; Windows; macOS, universal), runs
|
|
`games/hello-desktop` for real on each (its page must load and call PHP), and publishes the release
|
|
`tauri-<key>` (`tools/tauri-key.sh`: a hash of `tauri/`'s sources) that `tauri:download` and `app:export` use.
|
|
The micro of desktop apps for Windows and macOS is published by the workflow `standalone` run with the input
|
|
`extensions: tools/app-extensions.txt` (`tools/hybrid-extensions.txt`: hybrid games, Linux and Windows).
|
|
|
|
On Windows and macOS without Docker: a PHP 8.2+ with FFI (`ffi.enable=1`), `composer install` in the app, then
|
|
`JUMPHP_TAURI_LIB=<the library> php app.php`.
|
|
|
|
---
|
|
|
|
## Roadmap
|
|
|
|
Done: the runtime (Linux, Windows, macOS), PHP driving it from its main thread, windows, pages, page <-> PHP both
|
|
ways, native dialogs / notifications / opener / clipboard, menus, tray icon, global shortcuts, drag and drop, closing
|
|
decided by PHP, hybrid games (SDL + Tauri), tests without a window, real-window tests (Xvfb here, the three systems
|
|
on GitHub), one-file export for Linux and Windows, an `.app` and a `.dmg` for macOS, menus, updates, a hybrid game in
|
|
one window, starting with the computer.
|
|
|
|
Next:
|
|
- **Services / daemons** (an app or a CLI app running without a user session: Windows service, LaunchDaemon,
|
|
systemd unit; docs: TODO.md).
|
|
- **Signed apps**: macOS notarization and Windows Authenticode need the developer's certificates (the Apple
|
|
account, a code signing certificate); unsigned, the systems warn the first time.
|
|
- **iOS**: `bin/jumphp ios <app>` (a WKWebView on the browser build) is written but not tried on a Mac yet.
|
|
- More native features as Tauri plugins + `JumPHP\Native` providers.
|