UK

Comptes et données des utilisateurs : JumPHP\Platform\AppAccount

Une application JumPHP publiée sur jumphp.net peut donner à ses utilisateurs un compte (pseudo + mot de passe, pas d'e-mail) et garder leurs données sur le serveur pour les retrouver sur le PC, le téléphone et le navigateur, sans écrire de serveur à soi. JumPHP\Platform\AppAccount est le client PHP de cette « API plateforme » :

  • connexion : signUp(), signIn(), recover() (code de secours), signOut(), me(), devices(), revokeDevice(), hello() (présence), changePassword(), deleteAccount() ;
  • clé-valeur : get(), value(), set(), setText(), delete(), search() (préfixe, motif * ?, curseur), getMany() ;
  • objets entiers versionnés : put(), getObject(), versions(), objects(), deleteObject(), et store() / load() qui sérialisent un objet PHP et le relisent sans danger (seulement les classes que vous nommez).

Les mêmes appels marchent sur le bureau, dans le navigateur et sur Android. Ils ne bloquent jamais : chacun rend une JumPHP\Async\Task réglée à une image suivante (par $engine->http()). Le serveur, ses limites et ses codes d'erreur : Comptes d'application et Données des comptes d'application.

Démarrer

use JumPHP\Platform\AppAccount;
use JumPHP\Platform\AppAccountError;

$this->account = AppAccount::for($this->engine);          // l'application (project.yaml `id`) sur https://jumphp.net
// AppAccount::for($this->engine, 'mon-app')               // un autre nom sur la plateforme
  • L'adresse : https://jumphp.net/api/apps/<slug>/account. project.yaml platform_url ou JUMPHP_PLATFORM_URL (environnement ou page) en donnent une autre (un playground local) ; '' = pas de serveur (tests) : chaque appel échoue avec le code disabled.
  • L'application doit être publiée sur jumphp.net (sinon 404).
  • Le jeton de l'appareil est gardé dans var/jumphp-account.json (IndexedDB dans le navigateur, fichier 0600 sur le bureau) et envoyé en Authorization: Bearer. Jamais le mot de passe, jamais le code de secours.
  • Le type d'appareil (desktop, phone, web) est deviné ; le nom affiché dans la liste des appareils est « Computer », « Phone » ou « Browser » tant que l'utilisateur n'en donne pas un (dernier argument de signIn() / signUp()).

Se connecter

$this->account->signUp($pseudo, $motDePasse, 'PC salon')->then(
    fn (array $r) => $this->showRecoveryCode($r['recovery']),       // à montrer UNE fois : le seul moyen de revenir sans mot de passe
    fn (AppAccountError $e) => $this->error = $e->getMessage());   // $e->errorCode : login_taken, bad_login, bad_password, rate_limited...

$this->account->signIn($pseudo, $motDePasse)->then(fn () => $this->scenes()->switchTo(HomeScene::class));
$this->account->recover($pseudo, $code, $nouveauMotDePasse)->then(fn (array $r) => $this->showRecoveryCode($r['recovery']));
$this->account->signedIn();          // un jeton est là (au démarrage suivant aussi)
$this->account->signOut();           // oublié ici tout de suite, même hors ligne
$this->account->onSignedOut = fn () => $this->scenes()->switchTo(LoginScene::class);   // jeton révoqué ailleurs (401)

Présence et appareils : hello() toutes les 60 s ({online: [...], ...}), me(), devices(), revokeDevice($id).

Clé-valeur

Une clé : 1 à 128 caractères A-Z a-z 0-9 . _ : / -. Une valeur : n'importe quoi que json_encode() écrit (64 Ko), ou du texte.

$this->account->set('settings', ['volume' => 0.8, 'theme' => 'dark']);
$this->account->value('settings', [])->then(fn (array $s) => $this->apply($s));
$this->account->get('settings')->then(fn (?array $item) => $this->version = $item['version'] ?? 0);   // null : pas de clé
$this->account->setText('notes/courses', "pain\nlait");
$this->account->delete('settings');                                   // true, false si elle n'existait pas

// chercher : préfixe, motif sur toute la clé (* = n'importe quoi, ? = un caractère), page par page
$this->account->search(prefix: 'score:', match: '*-12', limit: 50, values: true)
    ->then(fn (array $page) => [$this->rows, $this->next] = [$page['items'], $page['next']]);
$this->account->search(prefix: 'score:', cursor: $this->next);      // la page suivante (next null : c'était la dernière)
$this->account->getMany(['settings', 'save/slot1'])->then(fn (array $r) => ...);   // {items, missing}

Deux appareils, une clé : écrivez avec la version lue ($ifMatch). Si un autre appareil a écrit entre-temps, la tâche échoue avec AppAccountError::isConflict() et $e->data['current'] (la valeur actuelle et sa version) : fusionnez et réécrivez.

$this->account->set('progress', $merged, $this->version)->then(
    fn (array $r) => $this->version = $r['version'],
    function (AppAccountError $e) use ($merged): void {
        if ($e->isConflict()) {
            $current = $e->data['current'];
            $this->account->set('progress', $this->merge($current['value'] ?? [], $merged), $current['version']);
        }
    });

$ifMatch = 0 : seulement si la clé n'existe pas encore ; null (par défaut) : la dernière écriture gagne.

Objets PHP entiers, versionnés

$this->account->store('save', $this->game, keep: 10)->then(fn (array $v) => $this->savedVersion = $v['version']);

$this->account->load('save', [Game::class, Player::class, Inventory::class])
    ->then(fn (?Game $game) => $this->game = $game ?? new Game(),        // null : rien d'enregistré
           fn (AppAccountError $e) => $this->error = $e->getMessage());   // unserialize : une classe hors de la liste...

$this->account->versions('save')->then(fn (array $h) => $this->history = $h['versions']);   // [{version, size, sha256, createdAt, device}]
$this->account->load('save', [Game::class, Player::class, Inventory::class], 3);           // revenir à la version 3 : la relire, puis store()
  • store() fait serialize() et envoie les octets (format php-serialize) ; le serveur ne les lit jamais. 2 Mo par version ; les keep dernières versions sont gardées (10 par défaut, 1 à 50).
  • load() exige la liste des classes permises : unserialize($octets, ['allowed_classes' => $liste]), jamais sans. Une classe absente de la liste, même tout au fond de l'objet, fait échouer la tâche (errorCode unserialize, data['class']) au lieu de rendre un objet à moitié fait. [] : des tableaux et des valeurs simples seulement. Les octets abîmés en route (SHA-256) sont refusés aussi. AppAccount::unserialize($octets, $classes) fait la même vérification pour vos propres octets.
  • Ne stockez que des données : pas de fermeture (Closure), de ressource, de texture SDL ni de scène ; un modèle à vous (Game, Player) avec des propriétés simples. Pour du JSON, un format à vous ou des octets : put($nom, $octets, 'json') / getObject().

Les erreurs

Toute tâche échoue avec un AppAccountError : getMessage() (le message du serveur, en anglais : traduisez à partir du code), errorCode, status (HTTP, 0 sans réponse), data (le reste de la réponse). Codes : ceux du serveur (bad_credentials, login_taken, bad_login, bad_password, revoked, unauthorized, not_found, version_not_found, version_conflict, quota, too_big, rate_limited avec data['retryAfter'], bad_key, bad_request, unsupported_type), et ceux du client : network (pas de réponse), disabled (pas de serveur), signed_out (pas de jeton : rien n'est envoyé), unserialize, damaged.

Un 401 autre que bad_credentials (appareil déconnecté ailleurs, compte supprimé) oublie le jeton et appelle onSignedOut.

Tester sans réseau

Le constructeur prend la fonction qui fait les requêtes : un faux serveur suffit.

$account = new AppAccount(function (string $method, string $url, ?string $body, array $headers, float $timeout): Task {
    $task = new Task();
    $task->settle(new HttpResponse(200, '{"login":"ada","token":"wzd_test","device":{"id":"a1b2c3d4e5f6"}}'));
    return $task;
}, 'https://jumphp.test/api/apps/mon-app/account', new Storage($dossierTemporaire));

Exemples : engine/tests/Platform/AppAccountTest.php.

Pour le propriétaire

Le serveur MCP du playground donne au propriétaire de l'application (à lui seul) les outils app_accounts_stats, list_app_accounts, get_app_account_data et delete_app_account : combien de comptes, leurs pseudos, ce que pèsent leurs données, le contenu d'un compte pour déboguer, la suppression d'un compte. Jamais un mot de passe ni un jeton.