Système de Hook

Le Système de Hooks dans TODD (ToddModule)

Le framework TODD (version orientée objet) dispose d'une architecture extensible reposant sur le concept de Hooks (crochets). Ces hooks permettent aux développeurs de modules (comme ToddBet ou ToddEvent) d'intervenir à des moments très précis du cycle de vie d'un composant, sans jamais avoir à modifier le cœur du système.

Cet article explique le fonctionnement de ce mécanisme destiné aux néophytes.

Comment c'est implémenté ?

L’implémentation technique des hooks dans TODD repose sur l'héritage objet (polymorphisme).

La classe mère ToddModule (dans libraries/class.todd_module.php) déclare une série de méthodes dites virtuelles (souvent vides par défaut ou contenant une logique de base). Par exemple :

protected function beforeSave(array &$payload): bool|string 
{
    return true; // Par défaut, passe à la suite sans bloquer
}

protected function afterSave(int $insertId, array $payload): void 
{
    // Rien par défaut
}

public function enqueuePublicAssets(): void 
{
    // Rien par défaut
}

Lorsqu'on crée un nouveau module, on crée une classe qui étend (extends) la classe mère ToddModule. Pour utiliser un hook, il suffit de redéfinir (override) cette méthode dans notre propre classe :

class ToddMonModule extends ToddModule 
{
    protected function beforeSave(array &$payload): bool|string 
    {
        // Mon code personnalisé ici !
        // Exemple : forcer un champ en majuscule avant la sauvegarde
        if (isset($payload['mon_titre'])) {
            $payload['mon_titre'] = strtoupper($payload['mon_titre']);
        }
        return true;
    }
}

Quel est le mécanisme interne ?

Le système central de TODD (par exemple todd.ws.php pour la sauvegarde Ajax, ou la méthode display() pour l'affichage public) orchestre le fonctionnement global.

La magie opère parce que le cœur s'engage à toujours exécuter ces méthodes à des instants stratégiques. Voici comment se comporte le script central de sauvegarde, traduit en logique simple :

1. Le cœur reçoit des données issues de l'interface d'administration.
2. Le cœur instancie le module concerné : $monModule = new ToddMonModule();
3. 🔔 Le cœur appelle en premier le hook : $resultat = $monModule->beforeSave($donnees);
4. Si le hook répond false ou un message d'erreur, le cœur stoppe tout.
5. Sinon, le cœur exécute sa propre tâche immuable : sauvegarder les données en base de données MMI.
6. Une fois fini, le cœur obtient un identifiant (ID) fraîchement créé.
7. 🔔 Le cœur appelle le hook suivant : $monModule->afterSave($ID, $donnees);

Ce mécanisme agit comment "des points de passage obligatoires" gérés par l’infrastructure. Si vous n'avez pas de code dedans, le cœur traverse une pièce vide et continue transparentement. Si vous avez défini un comportement, le cœur l'accepte et l'intègre au processus global.

Le Workflow d'un Hook en conditions réelles

Nous allons prendre l'exemple du workflow d'un utilisateur utilisant l'application, du début de la rédaction à l'affichage :

La préparation du formulaire d'édition

1. L'utilisateur ouvre la page pour éditer un module.
2. Le noyau TODD prépare le formulaire global de base.
3. 🪝 Appel de setupAdmin() : Votre module ajoute ses propres champs spécifiques (comme le "Form Builder" : un champ date, un champ nom d'équipe).
4. 🪝 Appel de enqueueAdminAssets() : Le noyau vous laisse charger vos fichiers JS/CSS, ce qui vous permet de rajouter de la vie au formulaire (ex : intégrer une modale d'import ESPN).

La sauvegarde (Utilisateur clique sur 'Sauvegarder')

1. Les données du formulaire sont envoyées en AJAX au serveur (todd.ws.php).
2. 🪝 Appel de beforeSave(&$payload) :
   • Ici, vous pouvez formater les données, valider que la date est au bon format, ou même bloquer la sauvegarde si, par exemple, un champ requis est manquant. "Attention : il manque l'équipe B !"
   • C'est aussi ici que vous pouvez intercepter des données virtuelles (qui n'appartiennent pas à la table principale de TODD) pour les stocker dans vos propres variables de classe.
3. Le noyau sauvegarde les données classiques (ID du composant, état en ligne, nom).
4. 🪝 Appel de afterSave($insertId, $payload) :
   • Le noyau vous dit : "C'est bon, le module TODD est sauvegardé sous l'ID #42. Tu as le feu vert pour sauvegarder tes trucs."
   • C’est ici que vous insérez les données spécifiques (date du match, scores, etc.) dans votre propre table métier (ex: my_app_todd_bet), rattachée via l'ID #42.

L’Affichage (le Visiteur lit la page)

1. Un visiteur charge la page Web comportant la mosaïque MMI.
2. Le moteur MMI demande à TODD d'afficher le bloc #42. TODD appelle $module->display().
3. 🪝 Appel de enqueuePublicAssets() : Le module charge ses propres feuilles de style public et son JavaScript front-end (ex: client.js).
4. 🪝 Appel de prepareDisplay($mode) : Le module récupère ses données métiers dans sa table secondaire (les scores, le sport de la ligue, etc.) et les prépare en de belles variables qui seront directement injectées et exploitables en PHP dans vos petits fichiers de vue (views/public_complete.php).
5. Le HTML fini est renvoyé et affiché sur l'écran final tactile.