Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01X3cUrphmz1MoDiCrUbAHuo
18 KiB
Applications de bureau (Tauri) : des pages HTML, du PHP derrière
English — la version anglaise est la référence complète (API détaillée, protocole C).
JumPHP fait des jeux (SDL : bureau, navigateur, téléphones) et des applications de bureau : des fenêtres natives dont le contenu est en HTML / CSS / JavaScript, affiché par la WebView du système, et dont la logique est en PHP. La fenêtre, la WebView, les boîtes de dialogue et les notifications viennent de Tauri 2 ; le programme, c'est PHP.
bin/jumphp app:new notes "Notes" # apps/notes à partir de skeleton-app/
bin/jumphp install notes
bin/jumphp app:run notes # une fenêtre sur ton écran
bin/jumphp app:test notes # php -l + phpstan + phpunit (sans fenêtre) + l'app pour de vrai sur un écran virtuel
bin/jumphp app:shot notes # apps/notes/var/screenshots/app.png
bin/jumphp app:export notes # apps/notes/dist/standalone/notes-linux-x86_64 : un seul fichier à donner
L'exemple : games/hello-desktop, un bloc-notes (ouvrir / enregistrer avec les boîtes
de dialogue du système, une horloge PHP envoyée à la page, des fichiers glissés sur la fenêtre, une question avant
de quitter si le texte n'est pas enregistré).
Natif uniquement. Les applications de bureau ne tournent pas dans le navigateur. Linux, Windows et macOS : le
runtime est compilé et essayé sur les trois par GitHub Actions ; l'export en un fichier existe pour Linux et
Windows. Un jeu peut aussi s'en servir : les jeux hybrides (ui: hybrid). Rien ne change pour les jeux : jeux SDL sur le bureau, dans le navigateur (WebAssembly), en
exécutable autonome, applis Android et Apple fonctionnent exactement comme avant ; aucun de leurs codes, images
Docker ou commandes n'utilise cette partie.
Le principe
PHP reste le programme principal, comme pour un jeu. Tauri est un backend de plateforme que PHP pilote :
app.php→JumPHP\Tauri\App::boot()→run(): PHP appellejt_run()de la bibliothèquelibjumphp_tauri.so(Rust, dossiertauri/) depuis son thread principal, par FFI ;- Tauri construit l'app et fait tourner sa boucle native (GTK sous Linux) sur ce thread ;
- à chaque frame (60 par seconde, et tout de suite quand il se passe quelque chose), Tauri rappelle PHP :
App::frame()lit les événements (jt_poll()), fait un tour de la boucle ReactPHP (timers, HTTP, tâches), et envoie ses commandes (jt_send()), exécutées juste après sur le thread principal ; - quand PHP demande à quitter,
jt_run()rend le code de sortie.
C'est le même modèle que le moteur navigateur (la page appelle jumphp_frame() à chaque
requestAnimationFrame). PHP ne bloque jamais : dialogues, sélecteurs de fichiers et appels des pages répondent
plus tard (une Task côté PHP, une Promise côté JavaScript). PHP décide : fermer une fenêtre ou l'app est un
événement auquel PHP répond (par défaut il ferme / quitte ; un listener peut faire preventDefault()).
Une seule bibliothèque pour toutes les apps : les pages sont servies depuis le dossier de l'app à l'exécution
(tauri://localhost/), pas compilées dedans.
Une app
apps/notes/
app.php exit(JumPHP\Tauri\App::boot(__DIR__)->run());
config/project.yaml ui: webview, main: App\Main, app: {...}
src/Main.php implémente JumPHP\Tauri\AppMain : commandes, listeners, timers
ui/ les pages : index.html, CSS, JS, images
assets/icon.png l'icône de la fenêtre
tests/MainTest.php étend JumPHP\Testing\AppTestCase
config/project.yaml :
project:
id: notes
title: "Notes"
version: 0.1.0
ui: webview # une app de bureau (run / test / shot passent la main aux commandes app:*)
main: App\Main
app:
pages: ui # dossier des pages
tick_hz: 60 # frames par seconde quand rien ne se passe
native_commands: true # les commandes native.* intégrées pour les pages
window: { url: index.html, width: 960, height: 640, min_width: 480, min_height: 320, devtools: false }
Côté PHP :
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) => "Bonjour {$p['name']}");
// une réponse qui vient plus tard : renvoyer une Task
$app->command('pick', fn () => FilePicker::open(['filters' => ['Texte' => ['txt', 'md']]]));
// PHP -> page : jumphp.on('clock', ...)
$app->gameLoop->addPeriodicTimer(1.0, fn () => $app->send('clock', ['time' => date('H:i:s')]));
// PHP décide de la fermeture
$app->window()->on('close-requested', function (NativeEvent $e) use ($app) {
$e->preventDefault();
Dialog::confirm('Quitter ?', 'Notes', 'Quitter', 'Rester')->then(fn ($oui) => $oui && $app->quit());
});
}
}
Côté page, window.jumphp est injecté avant les scripts de la page :
const r = await jumphp.invoke('greet', {name: 'Ada'}); // Promise : la réponse de PHP, ou le message de son exception
jumphp.send('clicked', {x: 1}); // PHP : $app->on('page:clicked', ...)
jumphp.on('clock', (p) => ...); // PHP : $app->send('clock', ...)
await jumphp.invoke('native.open', {filters: {Images: ['png', 'jpg']}}); // sans code PHP : native.message,
// native.confirm, native.open, native.save, native.notify, native.openUrl
En ligne de commande (sans fenêtre) : une classe main qui implémente aussi JumPHP\Tauri\AppCli reçoit d'abord
static cli(array $args, string $root): ?int, avant le chargement de la bibliothèque native : un code de sortie
s'arrête là (--help, --version, une installation silencieuse), null ouvre la fenêtre comme d'habitude.
Fonctions natives depuis PHP : JumPHP\Native
Les mêmes appels sur toutes les cibles ; ce qui les réalise dépend de l'endroit où le code tourne :
Dialog::message('Enregistré.', 'Notes');
Dialog::confirm('Supprimer ?', 'Notes', 'Supprimer', 'Garder')->then(fn (bool $oui) => ...);
FilePicker::open([...])->then(fn (?string $fichier) => ...); // aussi multiple, folder(), save()
Notification::show('Fini', 'Export terminé');
Shell::openUrl('https://jumphp.net');
Clipboard::copy('texte'); Clipboard::paste()->then(fn (string $t) => ...);
Native::supports('open'); // avant d'appeler
// apps et jeux hybrides : icône de zone de notification avec menu, raccourci global (même sans le focus)
$app->tray('main', ['tooltip' => 'Notes', 'menu' => [['id' => 'show', 'text' => 'Afficher'], '-', ['id' => 'quit', 'text' => 'Quitter']]])
->on('menu', fn (string $item) => $item === 'quit' ? $app->quit() : $app->window()->show());
$app->globalShortcut('CmdOrCtrl+Shift+K', fn () => $app->window()->show()->focus());
// menus (JumPHP\Tauri\Menu) : d'une fenêtre ($app->window()->setMenu()) ou de toute l'app ($app->setMenu()) ;
// éléments avec id (et raccourci), à cocher ('checked'), séparateurs ('-'), sous-menus ('items'), éléments du
// système ('role' : quit, about, copy, cut, paste, select_all, undo, redo, minimize, fullscreen, hide...).
// Sur macOS il n'y a qu'une barre de menus : celui d'une fenêtre devient celui de l'app.
$app->window()->setMenu([
['text' => 'Fichier', 'items' => [['id' => 'open', 'text' => 'Ouvrir...', 'accelerator' => 'CmdOrCtrl+O'], '-', ['role' => 'quit']]],
['text' => 'Affichage', 'items' => [['id' => 'wrap', 'text' => 'Retour à la ligne', 'checked' => true]]],
]);
$app->window()->on('menu', fn (string $item, ?bool $coche) => ...); // aussi $app->on('menu', fn ($item, $fenetre, $coche))
$app->window()->setMenuItem('wrap', ['checked' => false]);
| Cible | Fournisseur | Fonctions |
|---|---|---|
| app de bureau, jeu hybride | tauri |
toutes : message, confirm, open, save, folder, notify, openUrl, openPath, reveal, copy, paste |
| jeu SDL sur le bureau | sdl |
message (la boîte de message de SDL) |
| version navigateur | browser |
openUrl, copy |
| tests sans écran, ailleurs | none |
rien |
Ce qui manque à une cible fait échouer la Task avec UnsupportedFeature (ou renvoie false). En dessous restent
le FFI de PHP (n'importe quelle bibliothèque C du système) et les extensions PHP.
Jeux hybrides (SDL + Tauri)
Un jeu peut aussi piloter Tauri : ui: hybrid dans son config/project.yaml. Il reste un jeu SDL (scènes, fenêtre
SDL, son ; app.php inchangé) et gagne le côté natif des apps : JumPHP\Native, icône de zone de notification,
raccourcis globaux, et des fenêtres HTML à côté de la sienne (panneau de contrôle, éditeur, lanceur…). Exemple :
games/hello-hybrid (des balles en SDL, un panneau de contrôle en HTML, « enregistrer une
image » par le sélecteur de fichiers du système, un menu dans la zone de notification, Ctrl+Maj+P partout).
project:
ui: hybrid
main: App\Desktop # facultatif : un AppMain (commandes des fenêtres HTML, icône, raccourcis)
app:
window: {url: index.html, width: 340, height: 560} # facultatif : une fenêtre HTML (pages dans ui/)
Application::run() passe la main à JumPHP\Tauri\Hybrid : la boucle de Tauri appelle la frame de l'app, qui fait
un tour de ReactPHP, où le timer du jeu fait avancer le moteur comme d'habitude. Le jeu tourne comme un jeu
normal (sans Tauri) dans les tests sans écran, dans le navigateur, dans les applis téléphone, et sans FFI ou sans
runtime. bin/jumphp run le lance dans l'image Tauri ; export:standalone le fait avec un micro SDL et FFI
(tools/hybrid-extensions.txt).
Une seule fenêtre : app: {embed: true} met le jeu dans la fenêtre Tauri (JumPHP\Tauri\EmbeddedGame) :
SDL dessine chaque frame en mémoire (pas de fenêtre SDL), l'image passe au runtime (jt_frame()), la page de JumPHP
(engine/web/tauri/game.html) la dessine sur un canvas, nette et centrée, et renvoie clavier, souris et focus au
moteur (actions, F3, F11 marchent ; manettes lues par SDL). Fermer la fenêtre termine le jeu. Essayé pour de vrai
avec Pong sur Xvfb. Pour les grandes résolutions ou les jeux OpenGL, une fenêtre SDL reste préférable.
Tests
JumPHP\Testing\AppTestCase joue l'app sans fenêtre (un FakeRuntime : ni FFI ni GTK) ; le test fait la
page et l'utilisateur : invoke(), pageSend(), requestClose(), answerDialog(), frames(), wait(),
sent(), lastSent(). bin/jumphp app:test les lance puis fait tourner l'app pour de vrai sur Xvfb : échec
sur un warning PHP, une exception, ou si la page principale ne s'est jamais chargée.
Export : un seul exécutable
bin/jumphp app:export <app> réutilise export:standalone : le micro de StaticPHP avec les extensions des apps
(tools/app-extensions.txt : FFI, OpenSSL, mbstring…, sans SDL ; construit une fois, ~10 min, gardé dans
~/.jumphp/standalone), ffi.enable=1 injecté dans l'exécutable, l'app en PHAR et la bibliothèque Tauri. Au
premier lancement, l'app est dépaquetée dans ~/.cache/jumphp/<id>-<build> ; les fichiers de l'utilisateur vont
dans ~/.local/share/<id>.
L'ordinateur a besoin de WebKitGTK 4.1 (libwebkit2gtk-4.1-0 : Debian 12+, Ubuntu 22.04+, Fedora 39+) et
d'une glibc 2.34 ou plus récente, comme toute app Tauri sous Linux. Vérifié sur un Debian 13 nu avec seulement
libwebkit2gtk-4.1-0 (sans PHP).
L'export des jeux n'est pas touché : sans les variables des apps, export:standalone construit et retrouve le même
micro qu'avant (même clé).
Commandes
| Commande | |
|---|---|
app:new <app> [titre] |
apps/<app> depuis skeleton-app/ |
app:run <app> |
l'app sur ton écran (X11, sinon Wayland ; bus de session pour les notifications ; GPU) |
app:test <app> |
php -l, phpstan, phpunit, puis l'app pour de vrai sur Xvfb |
app:shot <app> [frames] [out.png] |
la fenêtre principale après N frames |
app:export <app> [--linux] [--windows] |
un exécutable Linux / Windows (.exe : WebView2, présent dans Windows 10 / 11) |
tauri:setup |
l'image jumphp/tauri (le runtime bureau + FFI + Rust + WebKitGTK) |
tauri:build |
tauri/ → build/tauri/linux-x86_64/libjumphp_tauri.so |
tauri:download [plateforme...|--all] |
la bibliothèque de ces sources depuis les releases GitHub : linux-x86_64, windows-x86_64, macos-universal |
Quand la bibliothèque manque ou est plus ancienne que ses sources, les commandes d'app la téléchargent (si la
release de ces sources existe), sinon la compilent. JUMPHP_TAURI_TRACE=1 affiche chaque commande et événement.
run, test et shot sur le dossier d'une app passent la main à app:run, app:test, app:shot ;
pages ne publie pas les apps (elles n'ont pas de version navigateur).
Dans le navigateur, sur téléphone
La même app tourne aussi dans une page web : bin/jumphp build <app> produit dist/web/ (fichiers statiques, comme un
jeu). Ses pages sont les mêmes (même window.jumphp), son PHP tourne dans le moteur WebAssembly de JumPHP
(JumPHP\Tauri\BrowserRuntime), et engine/web/jumphp-app.js fait en HTML ce que Tauri fait sur le bureau :
fenêtres (la principale remplit la page, les autres flottent), barre de menus et raccourcis, dialogues HTML,
sélecteur de fichiers du navigateur (copiés dans /tmp/open/ de PHP), enregistrement = téléchargement (ce que PHP
écrit dans /tmp/save/), notifications, presse-papiers ; icône de zone de notification et raccourcis globaux : rien.
Sur téléphone : la page telle quelle, bin/jumphp twa <app> --url ... pour Android (pwa: true), « Sur l'écran
d'accueil » sur iPhone. Essayé dans Chrome sans écran avec games/hello-desktop (salutation par PHP, menu, dialogue,
enregistrement téléchargé, aucune erreur). Une vraie app Tauri native Android / iOS (PHP embarqué dans l'app) n'est
pas faite : la boucle y appartient à l'activité / UIKit.
Linux : WebKitGTK installé par l'app
Une app Linux a besoin de WebKitGTK 4.1. S'il manque, l'app propose de l'installer avant d'ouvrir sa fenêtre
(JumPHP\Tauri\LinuxWebView) : elle reconnaît la distribution (Debian / Ubuntu / Mint, Fedora / RHEL, Arch /
Manjaro, openSUSE), demande (dans le terminal, sinon une boîte zenity / kdialog), installe avec les droits de
l'utilisateur (root, fenêtre de mot de passe pkexec, ou sudo), puis démarre. Refusé ou impossible : elle donne
la commande exacte et s'arrête. JUMPHP_INSTALL=yes installe sans demander, no dit seulement quoi faire. Essayé
sur Debian 13, Ubuntu 24.04, Fedora 42 et Arch nus. Windows (WebView2) et macOS (WKWebView) ont déjà leur WebView.
Export macOS et mises à jour
bin/jumphp app:export <app> --macos (depuis Linux, dans Docker) produit dist/standalone/<app>-macos.zip : une
<Titre>.app avec deux exécutables (Apple silicon, Intel), un lanceur qui démarre celui du Mac, Info.plist et
l'icône ; macOS 12 ou plus ; non signée (compte développeur Apple) : la première fois, clic droit > Ouvrir. Le
workflow app-export l'exporte, l'ouvre pour de vrai sur un Mac Apple silicon et un Mac Intel, puis fabrique son
.dmg (hdiutil n'existe que sur Mac) : l'artefact dmg du run, <app>-macos.dmg (l'app et un lien vers
Applications où la glisser).
Une app exportée se met à jour elle-même ($app->updater()) : bin/jumphp app:release <app> --url <adresse> [--notes "..."] [--linux] [--windows] [--macos] exporte l'app et écrit un update.json signé (clé ECDSA dans
~/.jumphp/keys/<id>-update.pem, à garder précieusement ; sa moitié publique dans config/update.pub, à commiter) ;
on dépose dist/standalone/ à cette adresse, et project.yaml app: {update: {url: <adresse>/update.json}}.
check() vérifie la signature et la version, install() télécharge, vérifie le SHA-256 et remplace l'exécutable,
relaunch() relance. games/hello-desktop a Aide > Check for updates (essayé pour de vrai : la 0.1.0 a trouvé,
installé et relancé la 0.1.1). Détails : tauri.md.
Démarrer avec l'ordinateur
Une app exportée peut se lancer quand l'utilisateur ouvre sa session (sans droits administrateur ;
JumPHP\Native\Autostart) : $app->autostart()->set(true) (ou false), isSupported() (une app exportée sous
Windows, macOS ou Linux, pas php app.php), isEnabled(), startedAtLogin() (lancée par l'ordinateur : le drapeau
--autostart). Windows : la valeur <id> de HKCU\Software\Microsoft\Windows\CurrentVersion\Run ; macOS : un
LaunchAgent ~/Library/LaunchAgents/<identifier>.plist qui ouvre la .app ; Linux : ~/.config/autostart/<id>.desktop.
project.yaml app: {autostart: {default: true, hidden: true}} : activé au premier lancement (une fois, ensuite
l'utilisateur décide), fenêtre principale cachée quand l'ordinateur l'a lancée (une app de la zone de notification).
Une page demande avec jumphp.invoke('native.autostart', {on: true}). Exemple : games/hello-desktop, View > Start
with the computer.
Plateformes
Le workflow .github/workflows/tauri.yml (à chaque changement de tauri/ ou du côté PHP, ou à la main) compile la
bibliothèque sur Linux (Ubuntu 22.04 : glibc 2.35+), Windows et macOS (universelle), lance games/hello-desktop pour
de vrai sur chacun (la page doit se charger et appeler PHP), et publie la release tauri-<clé> qu'utilisent
tauri:download et app:export. Le micro des apps pour Windows est publié par le workflow standalone lancé avec
extensions: tools/app-extensions.txt. Sous Windows et macOS sans Docker : un PHP 8.2+ avec FFI (ffi.enable=1),
composer install, puis JUMPHP_TAURI_LIB=<la bibliothèque> php app.php.
Feuille de route
Fait : le runtime (Linux, Windows, macOS), PHP qui le pilote depuis son thread principal, fenêtres, pages, page ↔ PHP, dialogues / notifications / liens / presse-papiers, menus, icône de zone de notification, raccourcis globaux, glisser-déposer, fermeture décidée par PHP, jeux hybrides, tests sans fenêtre et en vraie fenêtre, export Linux, Windows et macOS, mises à jour.
Ensuite : la signature des apps (certificats du développeur), Android et iOS (la boucle y est pilotée par
l'activité / UIKit ; à la place, bin/jumphp android <app> et bin/jumphp ios <app> mettent la version navigateur de
l'app dans la WebView du téléphone, voir docs/tauri.md ; Android essayé, iOS pas encore), d'autres fonctions natives.