Framework

Créer un module additionnel

Table des matières

Avant propos

Vous souhaitez créer un module additionnel, vous êtes au bon endroit. Cet article se veut le plus complet possible afin de vous aider au mieux à utiliser le framework proposé par PHPBoost.

Attention cet article n'est pas un cours de PHP, ni de PHP avancé, cet article s'adresse à des programmeurs PHP confirmés. Certaines notions sont en effet relativement complexe à aborder. Toutefois tout dépend de la complexité de ce que vous souhaitez réaliser.

Le framework PHPBoost est un ensemble d'outils proposés aux développeurs. Ces outils sont utilisés de façon récurrente dans les modules. Le fait d'utiliser ces outils permet d'assurer une grande cohérence entres les modules développés par des personnes différentes. La difficulté réside donc dans le fait qu'il faut s'adapter à la technique de programmation utilisée. Mais une fois ceci fait la vitesse de développement et de débuggage s'en retrouve démultipliée. En effet n'importe quel développeur pourra s'y retrouver car connaissant déjà ces outils.

Cet article va donc détailler le prototype d'un module. Certaines règles ne sont pas obligatoires (ce sera clairement mentionnée) mais le fait de les respecter assure à votre module un succès garantit auprès des développeurs.

Plusieurs points seront détaillés dans des articles connexes, consultez les pour appronfondir vos connaissances sur le framework.

Structure des fichiers d'un module

Avant de commencer à proprement parler la partie programmation, il est important de mettre en place les fichiers pour pouvoir commencer à travailler.
Cette partie est très importante car elle va vous permettre de comprendre l'organisation et la structure d'un module.

Pour commencer que-ce qu'un module?

Un module en faisant une comparaison avec l'ordinateur est en quelque sorte un nouveau logiciel que vous installez sur votre ordinateur. Pour cela il doit pouvoir être installé et désinstallé. Mais avant cela il doit être reconnu par le système d'exploitation. Il doit donc respecter des règles précises sinon il ne pourra même pas être installé ou au mieux fonctionnera anormalement.

On suppose que votre module s'appele votremodule (/votremodule). Il faut tout d'abord créer un dossier à la racine du même nom que votre module.

Fichiers de configuration

Tout d'abord il faut un fichier de configuration du module, pour préciser ses fonctions au noyau PHPBoost. Ce fichier contient des variables dépendantes de la langue, donc ce fichier est dupliqué autant de fois qu'il y a de langue disponibles pour le module.

Un conseil, faire évoluter votre fichier config.ini au cours du développement au fur et à mesure que vous intégrez de nouvelles fonctions.

Créez un dossier /lang qui contiendra des dossiers pour chaque langues.
Créez un dossier /french à l'intérieur du dossier /lang.
Créez un fichier config.ini à l'intérieur du dossier /lang/french/.

L'arborescence doit ressembler à ça:
/votremodule

/lang

/french

config.ini

Attention les fichiers .ini doivent être formatés d'une certaine façon. Les valeurs associées aux clées doivent être entourées de guillement double (") s'il s'agit d'une chaîne de caractère.

Le fichier config.ini doit être sous cette forme:

Code TEXT :

name="Nom de votre module"<br />
author="CrowkaiT, ben.popeye"<br />
author_mail="[email protected], [email protected]"<br />
author_link="http://www.phpboost.com"<br />
version=2.0<br />
info="Desciption de votre module"<br />
date="30/01/08"<br />
compatibility=2.1<br />
admin=1<br />
admin_links=""<br />
css=1<br />
cache=1<br />
sql_table=8<br />
starteable_page="index.php"<br />
moderation_panel=1<br />
config=1<br />
com=""<br />
mini_module=0<br />
url_rewrite=""

name : Nom de votre module.
author : Auteur(s) du module.
author_mail : Mails des auteur(s) du module.
author_link : Site web des auteur(s) du module.
version : Version du module.
info : Description du module.
date : Date de création.
compatibility : Numéro de version du noyau compatible avec ce module.
admin : Possède un panneau d'administration? Mettre 1 si oui, 0 si non.
admin_links: Permet d'afficher des sous menus dans l'administration dans les listes déroulantes. La chaine doit être formaté comme un tableau php sans mettre la structure de language array.
css : Utilise un css alternatif ? Mettre 1 si oui, 0 si non.
cache : Utilise le cache? Mettre 1 si oui, 0 si non.
sql_table : Nombre de table SQL utilisées.
starteable_page : Possède une page de démarrage? Mettre la page si oui, laissez vide si non.
moderation_panel : Possède un panneau de modération ? Mettre 1 si oui, 0 si non.
config : Possède une entrée dans la table de configuration ? Mettre 1 si oui, 0 si non.
com : Intègre un système de commentaires ? Mettre 1 si oui, 0 si non.
mini_module : Le module possède un mini module associé? Mettre 1 si oui, 0 si non.
url_rewrite : Si non vide, ajoute une règle de réecriture au fichier .htaccess, pour en savoir plus consultez l'article url rewriting

Fichiers de langues

Vous avez déjà créer un dossier /french dans le dossier /lang dans l'étape précedente.
Votre fichier de langue du module doit s'appeler: votremodule_french.php

Pour la langue anglaise il aurait fallu créer un dossier /english dans le dossier /lang et le fichier aurait dû s'appeler votremodule_english.php

Les fichiers de langues contiennent les langues dans un tableau associatif $LANG
Exemple:

Code PHP :

$LANG['votremodule_exit'] = 'Exit';

A noter qu'il est important de préfixé le nom de la clée par le nom de votre module

Fichiers d'installation

Si votre module a besoin d'exécuter des actions à l'installation il faudra créer des fichiers d'installation afin que ceux-ci soit exécutés. Les fichiers exécutés à l'installation peuvent être des fichiers SQL et/ou des fichiers PHP.

Créez un dossier /db

Comme certaines requêtes sont dépendantes de la langue, vous devez créer un dossier pour chacune des langues supportées par le module.

Créez un dossier /french dans /db
Créez un fichier votremodule.mysql.sql (si le module utilise la base de données). A noter que vous pouvez ajouter un fichier votremodule.SGBD.sql pour un autre système de gestion de base de données (SGBD) si votre module le gère.
Créez un fichier votremodule.php (si le module doit exécuter ce fichier pour s'installer).

C'est également dans ce dossier que vous mettrez les fichiers de mise à jour du module.

Fichiers de templates

Les templates représentent le squelette de vos pages, pour plus d'avantage d'information consultez l'articles sur les templates. _____

Créez un dossier /templates

Vous pouvez également créer un dossier images à l'intérieur pour séparer les images des templates. N'oubliez pas que ces images ne seront pas dépendant du thème choisi. Pour que votre module s'adapte à chaque thème il faut que ce dossier templates soit placé dans le thème et soit renommé en votremodule. Pour rendre l'adresse variable dans le template consultez l'article: _____

Arborescence finale

/votremodule

/db

/french

votremodule.mysql.sql

votremodule.php

/lang

/french

config.ini

votremodule_french.php

/templates

fichiers.tpl

fichiers.php

Cohérence des modules

Style de programmation

Il est important dans un projet que les développeurs adopent un style d'indentation identique. Ceci favorise la relecture du code et le débuggage.

Cet règle n'est pas obligatoire, mais très fortement recommandée. Vous pouvez donc passer à la partie suivante si vous le souhaitez.

Les conditions
if/elseif/else. Un espace avant la parenthèse, pas d'espace à l'intérieur.

Code PHP :

if ($var == 2)
{
echo '$var vaut 2';
}

Avec traitement sur plusieurs lignes:

Code PHP :

if ($var == 2)
{
echo '$var vaut 2';
$var = 3;
}
elseif ($var == 3)
{
echo '$var vaut 3';
$var = 4;
} 
else
{
echo '$var vaut 4';
}

Avec imbrication:

Code PHP :

if ($var > 1)
{
if ($var == 2)
{
echo '$var vaut 2';
$var = 3;
}
else
{
echo '$var différent de 2';
$var = 4;
}
}

Les boucles

Code PHP :

for ($i = 0; $i < 5; $i++)
{
echo $i;
}

Code PHP :

$i = 0;
while ($i < 5)
{
echo $i;
$i++;
}

Cohérence dans la sécurité

La sécurité est la partie la plus importante du projet, aussi bon soit-il, si la fiabilité n'est pas là, un logiciel est voué à sa perte. De plus une fois la crédibilité mise en cause il est difficile de changer d'image. C'est pourquoi cette partie doit-être lue avec le plus grand intérêt et sérieux.

Cohérence avec la programmation orientée objet

Par convention, toutes les variables commencent par une minuscule, y compris les objets. Ceci n'est pas vrai pour les variables globales telles que

$Cache

$Sql

qui elles commencent par une majuscule.

Vous ne devrez donc pas utiliser de variables commençant par une majuscule si ce n'est pas une variable globale, au risque d'écraser cette variable existante et de rendre le compte plus dur à comprendre.

Par convention les méthodes des objets s'écrivent en minuscules avec des _ comme séparateur. Les méthodes privées elles commencent toujours par le caractère _. Les variables d'instances elles s'écrivent en minuscules et ne doivent jamais être appelées de l'extérieur de l'objet, tout comme ses méthodes privées.

D'une manière générale, les variables s'écriront toujours de la forme :

Code PHP :

$ma_variable_a_moi

les variables globales :

Code PHP :

$MaVariable

Code PHP :

$MA_VARIABLE

les fonctions et méthodes publiques :

Code PHP :

function ma_methode()
{
    // Code de la méthode
}

Les méthodes privées ou protégées :

Code PHP :

function _ma_methode()
{
    // Code de la méthode privée
}

Information générales

Pour pouvoir développer, voici quelques informations essentielles.

Les invités ont pour niveau d'autorisation -1
Les membres ont pour niveau d'autorisation 0
Les modérateurs ont pour niveau d'autorisation 1
Les administrateurs ont pour niveau d'autorisation 2

Ces simples autorisations peuvent être finement modulés par les groupes (qui ont la possibilité d'être multiples).

Framework PHPBoost

Données accessibles

Configuration

La variable $CONFIG est un tableau contenant toutes les informations de configuration du site.
Voiçi le détail de chacune des valeurs:

Code TEXT :

$CONFIG['server_name'] :  Adresse du serveur <br />
$CONFIG['server_path'] : Chemin vers PHPBoost<br />
$CONFIG['site_name'] : Nom du site<br />
$CONFIG['site_desc'] : Description du site<br />
$CONFIG['site_keyword'] : Mots clés du site<br />
$CONFIG['start'] : Timestamp de l'installation du site<br />
$CONFIG['version'] : Version de PHPBoost<br />
$CONFIG['lang'] : Langue par défaut<br />
$CONFIG['theme'] : Thème par défaut<br />
$CONFIG['editor'] : Editeur texte par défaut<br />
$CONFIG['timezone'] : Heure du site en GMT<br />
$CONFIG['start_page'] : Page de démarrage<br />
$CONFIG['maintain'] : Timestamp de la fin de la période de maintenance<br />
$CONFIG['maintain_delay'] : Affichage du délai de maintenance<br />
$CONFIG['maintain_display_admin'] : Afficher le délai de maintenance à l'admin.<br />
$CONFIG['maintain_text'] : Texte de la maintenance<br />
$CONFIG['rewrite'] : Url rewriting<br />
$CONFIG['com_popup'] : Commentaires en popup<br />
$CONFIG['compteur'] : Affichage du compteur<br />
$CONFIG['bench'] : Benchmark du site<br />
$CONFIG['theme_author'] : Affichage de l'auteur du thème<br />
$CONFIG['ob_gzhandler'] : Activation de la compression des pages<br />
$CONFIG['site_cookie'] : Nom du cookie de connexion<br />
$CONFIG['site_session'] : Durée de la session membre<br />
$CONFIG['site_session_invit'] : Durée de la session invité<br />
$CONFIG['mail'] : Mail(s) de l'administrateur<br />
$CONFIG['activ_mail'] : Envoyer les mails à l'administrateur<br />
$CONFIG['sign'] : Signature du mail<br />
$CONFIG['anti_flood'] : Activation de l'anti-flood<br />
$CONFIG['delay_flood'] : Durée pour l'anti-flood<br />
$CONFIG['unlock_admin'] : Clée de déverrouillage de l'administration<br />
$CONFIG['pm_max'] : Messages privés maximum par défaut

Les variables les plus intéressantes sont $CONFIG['theme'] et $CONFIG['lang'] qui vous permettront respectivement de récupérer le thème et la langue de l'utilisateur (quand l'utilisateur est connecté, ses préférences modifies ces variables en conséquence).

Variables utilisateur

Pour récupérer des informations sur un membre, il faut récupérer ses attributs. La méthode Get_attribute() _____ vous permet de récupérer les propriétés suivantes:
Voiçi le détail de chacune des valeurs:

Code TEXT :

$User->Get_attribute('user_id') : Id de l'utilisateur, -1 si invité<br />
$User->Get_attribute('login') : Pseudo de l'utilisateur, Invité si invité<br />
$User->Get_attribute('level') : Niveau d'autorisation de l'utilisateur, -1 si invité<br />
$User->Get_attribute('user_groups') : Groupes de l'utilisateur, séparés par des |<br />
$User->Get_attribute('user_lang') : Langue de l'utilisateur<br />
$User->Get_attribute('user_theme') : Thème de l'utilisateur<br />
$User->Get_attribute('user_mail') : Mail de l'utilisateur<br />
$User->Get_attribute('user_pm') : Nombre de messages privés de l'utilisateur<br />
$User->Get_attribute('user_readonly') : Utilisateur en lecture seule?<br />
$User->Get_attribute('user_editor') : Editeur texte de l'utilisateur<br />
$User->Get_attribute('user_timezone') : Zone horaire de l'utilisateur (GMT)

La variable la plus intéressante est $Member->Get_attribute('user_id') qui vous donne l'identifiant du membre.
A noter que vous pouvez également récupérer les valeurs inséré dans les champs membre supplémentaire. Pour en savoir plus _____

Utilisation du framework

Certaines fonctions sont plus bas niveau que d'autres et donc plus ou moins difficiles à appréhender. Cet article fait en sorte de vulgariser (au bon sens du terme) certaines notions relativement avancée d'informatique afin de vous aidez à comprendre ce qui se pose derrière chaque fonction. Toutefois vous pouvez simplement vous servir de certains outils comme des boites noires et donc ne pas comprendre leur fonctionnement.

Cette partie ne doit pas obligatoirement être lue linéairement même si les chapitres sont classés par ordre de difficulté. Vous pouvez vous référer à une fonction précise sans lire les précédentes.

Vérification des droits d'accès

Les droits d'accès dépendent du niveau d'autorisation du membre ($Member->Get_attribute('level') ou d'autorisations spécifiques au groupes (voir pour plus de détails, la Gestion des groupes_____).

La fonction Check_level de la classe Membre permet de contrôler l'accès suivant le niveau d'autorisation.

Code PHP :

if( $Member->Check_level(0) ) 
echo 'Vous avez le niveau de membre ou plus';
if( $Member->Check_level(1) ) 
echo 'Vous avez le niveau de modérateur ou plus';
if( $Member->Check_level(2) ) 
echo 'Vous avez le niveau d'administrateur';
echo 'Vous avez le niveau visiteur ou plus';

Utilisation des templates

Consultez l'article Utilisation des templates _____

Utilisation de la base de données

Consultez l'article Utilisation de la base de données _____

Formulaires pour ajouter/modifier du contenu et traitement associé

Générer automatiquement une pagination

Consultez l'article Pagination _____

Intégration du gestionnaire de commentaires

Consultez l'article Intégration du gestionnaire de commentaires _____

Fonctions générale

Envoyer un message privé

Consultez l'article Envoi de messages privés _____

Envoyer un mail

Consultez l'article Envoi de mail _____

Générer un flux rss

Uploader un fichier

Consultez l'article Uploader un fichier _____

Fonctions avancées

Utilisation du cache

Consultez l'article Gestion du cache _____

Utilisation des droits sur les groupes

Consultez l'article Gestion des groupes _____

Utilisation de l'Ajax

Consultez l'article Utilisation de l'Ajax _____