FAQ : Développement de modules

2013-09-18T07:36:05Z

Tortukitu :

FAQ : Développement de modules

2013-09-18T07:32:46Z

Tortukitu :

2013-09-17T19:58:07Z

Tortukitu :

== Introduction ==

Avec l'age, de nombreuses fonctionnalitées ont été rajoutées à HackBBS. La qualité originelle du code et les modifications successives ne permettent plus d'avoir quelque chose de maintenable. C'est dans cette optique que la refonte du site a été envisagée.

== Équipe ==

* Korigan : CDP, dev
* TorTukiTu : Architecte, dev
* Vous ?

== Liste des tâches ==

FAIT - Concevoir et Développer la GUI (IHM) - Tortukitu

FAIT - Concevoir et Développer le noyau - Tortukitu

A faire - Créer le dépot GIT

A faire - (Optionnel) Créer le système de gestion de projet (Redmine ? autre ?)

A faire - Développer le métier du noyau

A faire - Développer la couche consumer

A faire - Développer une API pour brancher les challenges

== Contraintes ==

* Utiliser l'installation et la configuration actuelle du serveur Apache2
* Utiliser des technologies les plus connues et les plus répandues possibles. (Ce qui permettra une implication plus large de la communautée)
* Utiliser des technologies permettant une modularité
* Utiliser des technologies pouvant s'interfacer avec MySQL (Réutilisation de la base de données existante)
* Limiter au maximum l'utilisation de frameworks pour que le projet soit maintenable avec un bagage de connaissances minimum

== Technologies retenues ==

* PHP
* PDO
* Ajax

== Architecture ==

Il s'agit d'une architecture 3 couches:
* Une couche gère l'interface utiisateur
* Une couche contient le code métier
* Une couche consomme les différents services (Tape dans les bases de données, envoie les emails, etc.).

Le diagramme ci dessous vous présente l'architecture retenue. Une ligne pleine représente une notion de dépendance, une ligne pointillée un flux de communication.

hxxp://imagik.fr/view-rl/48310

La communication entre les couches '''DOIT''' suivre le sens indiqué par les flèches. Par exemple, appeller des fonctions dans la couche Consumer depuis la couche Business est autorisé. Par contre appeller des fonctions de la couche Business depuis la couche Consumer est interdit.

Une approche par script de transaction a été choisie. Ce qui signifie que les objets du modèle ne '''DOIVENT JAMAIS''' comporter des fonctions métier de traitement.

D'une manière plus générale, retenez seulement que vos modules ne devraient accéder '''QUE''' a la couche business du noyau (et les couches transversales tel que le modèle ou la sécurité).

L'ensemble de l'application est extensible via l'utilisation de modules (cf. schéma).

=== Couche provider (Interface utilisateur) ===

Une interface de type "terminal" a été retenu. Ce type d'interface pose en temps normal des problèmes d'expérience utilisateur, mais s'agissant d'un site de chall, ceci n'entre pas vraiment en ligne de compte.
La gestion du terminal est effectué par des fonctions javascript utilisant la lirairie JQuery et ses extensions jTerminal et JQueryUI.

La communication entre le client et le serveur se fait en JSON. C'est en fait un objet DataBusVO sérialisé qui est échangé entre le client et le serveur. La sérialisation est gérée par le script dispatcher.php

L'ensemble du travail des modules consiste donc à générer une instance de DataBusVO qui sera récupérée par dispatcher.php pour modifier l'affichage côté client.

Les fichiers de cette couche sont situés dans le répertoire '''/ et /resources'''.

=== Couche business (métier) ===

La couche métier présente des services aux couches supérieures. Ces services consistent en des singletons ou, plus exotiquement, des fonctions statiques.
Les services présentés sont les suivants:
* LoaderService : Gère le chargement dynamique des modules.
* SecurityService : Fourni des fonctions de vérification des permissions des utilisateurs
* SessionService : Gère l'étanchéité des variables de sessions entre différents modules, fournis des fonctions de récupération de l'utilisateur courant
* UserService : Fournis des fonctions de CRUD des utilisatuers, de vérification de connection d'un utilisateur
* SanitizerService : Fournis des fonctions de nettoyage des variables utilisateur.

Les fichiers de cette couche sont situés dans le répertoire '''/php/core_services/business''' et '''/php/modules'''.

=== Couche consumer (consommateur de services) ===

Cette couche conient des services de manipulation de la base de données et d'envoi d'emails.

Les fichiers de cette couche sont situés dans le répertoire '''/php/core_services/consumer'''.

=== Couche transversale : modèle ===

Cette couche contient des objets porteurs de données dont les instances sont transportés d'une couche à l'autre. Par exemple, la couche consumer crée une instance de User qui est renvoyé à la couche Business.

Les fichiers de cette couche sont situés dans le répertoire '''/php/model'''.

=== Couche transversale : sécurité ===

TODO.

=== Couche transversale : logging ===

TODO.

== Configuration ==

La configuration (données d'accès aux bases, définition des modules à charger) se trouve dans le fichier hackbbsConf.ini dans le répertoire /php/conf/

[[Détail du fichier de confguration]]

== Développement de modules ==

Un module (ici Monmodule) est consitué de trois éléments:
* Une implémentation de l'interface IModule (''obligatoire'') appellé par convention MonmoduleModule.
* Un dossier (''optionnel'') appellé par convention monmoduleModule.
* Une déclaration names[] = Monmodule dans le fichier de configuration hackbbsConf.ini (''obligatoire'').

'''ATTENTION ! Tous les modules doivent se trouver dans le dossier /php/modules. Veillez à bien respecter les conventions de nommage. Sinon, votre module ne sera pas chargé par le LoaderService et ne sera pas disponible dans le terminal.'''

=== Implémentation de IModule ===

L'interface à implémenter (/php/contract/IModule) compte 3 fonctions :

* function canHandleData($data) : $data est la String que l'utilisateur a entré dans le terminal. Renvoyez true si votre module doit se charger de réaliser l'opération demandée par l'utilisateur, false sinon.
* function manageData($data) : $data est la String que l'utilisateur a entré dans le terminal. Ici, réalisez vos traitements, puis renvoyez une instance de DataBusVO contenant les actions que vous voulez effectuer sur le terminal. Voir la page [[Contrôle du terminal via DataBusVO]].
* function getPrototype() : Renvoie String contenant une description rapide de la commande en HTML. Typiquement macommande : Ce que fait ma commande.

Ci dessous une implémentation de démonstration de IModule

<tt>
class MonmoduleModule implements IModule{
public function canHandleData($data) {
$ans = false;
if($data == "macommande"){
$ans = true;
}
return $ans;
}
public function getPrototype() {
return "macommande : Ce que fait ma commande";
}
public function manageData($data) {
$dataBus = new DataBusVO();
$dataBus->setHtmlData("Cette comande ne fait rien de particulier.");
return $dataBus;
}
}
</tt>

=== Modification du fichier de configuration ===

Ajouter la ligne :

names[] = Monmodule

A la fin de la section [modules] du fichier /php/conf/hackbbsConf.ini

=== Répertoire monmoduleModule ===

Contient tous les fichiers spécifiques au mondule monmodule. Si nécéssaire, découper en couches business, model et consumer.

'''REMARQUE''' : ''Entorse à l'architecture pendant la partie refonte de HackBBS.. Un développeur de modules ne devrait jamais toucher au noyau. Or, '''la plupart du métier (et modèle) développé aujourd'hui sera nécéssaire à un grand nombre de futur modules. Il est donc de bon ton d'ajouter au métier du noyau les fonctions et services que l'on saura réutilisés dans la suite des développements'''. Ceci est laissé à l'appréciation du développeur. Lorsque la refonte sera terminé, il deviendra interdit aux futurs développeurs de toucher au code du noyau pour y ajouter de nouvelles fonctionnalitées.''

== Règles générales ==

* A toute classe son interface.
* Jamais de copier coller
* '''Respecter l'architecture'''
* Ne jamais utiliser directement $_SESSION, toujours passser par le service SessionService (sauf exceptions autorisées par l'architecte)
* '''Chaque classe et fonction doit être commentée'''
* (Optionnel) Écrire une page de wiki par module
* (Optionnel) Si vous avez le temps, les tests unitaires, c'est bien