winzik/docs/tauri.fr.md

291 lines
18 KiB
Markdown

# Applications de bureau (Tauri) : des pages HTML, du PHP derrière
[English](tauri.md) — 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](https://tauri.app) ; le programme, c'est PHP.
```bash
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`](../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](#jeux-hybrides-sdl--tauri) (`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 :
1. `app.php` → `JumPHP\Tauri\App::boot()` → `run()` : PHP appelle `jt_run()` de la bibliothèque
`libjumphp_tauri.so` (Rust, dossier `tauri/`) **depuis son thread principal**, par FFI ;
2. Tauri construit l'app et fait tourner sa boucle native (GTK sous Linux) **sur ce thread** ;
3. à 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 ;
4. 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` :
```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 :
```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 :
```js
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 :
```php
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`](../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).
```yaml
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](tauri.md#updates).
## 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.