Documentation du Framework Puzzle

Principes de Base

Puzzle utilise le Design Pattern MVC (Model-View-Controller).
Ce design pattern consiste à faire passer les requêtes vers le Controlleur Associé, qui se chargera à son tour de mettre en forme la Vue pour la réponse.
Si le Controlleur doit accéder à une base de donnée, il se sert alors du Modèle.

Cette structure permet d'établir une architecture organisée et simple à modifier.
En effet, si jamais des changements devraient avoir lieu sur la base de donnée, il suffirait alors d'adapter uniquement le Modèle. Le Controlleur se servant de ce dernier, et celui-ci étant à jour, il serait donc capable de restituer la Vue en bonne et dûe forme.

Par ailleurs, Puzzle tiens son nom car il à été développé pour que le développeur puisse uniquement charger ce dont il à besoin.
(ceci sera développé par la suite de cette documentation - cf. Classes).

Requêtes

Les requêtes sont toujours interprétées de la manière suivante:


Par exemple:

> http://www.monsite.com/blog/mon-titre-darticle/

Organisation

L'organisation est la suivante:

• / (dossier racine)
  • /cache/ (dossier des fichiers temporaires)
  • /config/ (dossier des fichiers de configuration)
  • /controllers/ (dossier ou se trouvent les Controlleurs)
  • /i18n/ (dossier des fichiers de traduction)
  • /log/ (dossier des fichiers log - pas encore développé)
  • /models/ (dossier des modèles)
  • /puzzle/ (dossier des fichiers "core" du Framework)
  • /site/ (dossier ou résident les fichiers joints au site (images, javascripts, css ...)
  • /views/ (dossier des Vues)
  • .htaccess (fichier se chargeant de la redirection des requêtes vers index.php)
  • index.php (fichier "Bootstrap" - permettant le dispatch vers les Controlleurs)

En cas de non-support du mod_rewrite, les requêtes peuvent passer par le fichier index.php, par exemple: http://www.monsite.com/index.php/controlleur/variable/action/

Si vous souhaitez placer des Controlleurs "invisibles" (c'est à dire pas accessible par une requête web) vous pouvez les nommer _moncontrolleur.php.
Ceci est identique pour les fonctions (dites 'actions') des Controlleurs.

L'action par défaut d'un Controlleur est 'index'.
Ceci est configurable dans le fichier puzzle/defines.inc

A chaque Controlleur, une Vue. Le modèle n'est pas nécessaire mais sera chargé automatiquement si présent.
Tous doivent porter le même nom.
- Un controlleur est une Classe qui hérite de pzController (Class MonControlleur? extends pzController)
- Un modèle est une Classe qui n'a pas de parent.

Les Classes

Note: Certaines classes peuvent nécessiter des paramètres de configuration, ceux-ci étant détaillés dans le fichier config.inc.php

Lorsque vous souhaitez utiliser une classe du Framework dans vos Controlleurs, vous pouvez l'appeler de cette manière.
> pzEngine::getClass('nom_de_classe');

par exemple, pour utiliser la classe qui se charge d'accéder à la base de donnée:
> $db = pzEngine::getClass('database');
> $db->query("SELECT * FROM exemple");

Note: le nom de la classe ne prend pas le prefixe "pz".

Les Classes "Core"

Généralement, ces classes sont utilisés par Puzzle lui-même. Vous n'aurez sans doute pas besoin de les charger manuellement.
Afin d'obtenir de plus amples informations sur les Classes et pour maitriser leurs fonctionnements, référez-vous au code de celles-ci.
Celles-ci sont:

- pzEngine

• pzView
• pzGeoip
• pzi18n
• pzController
• pzLog

Vous pouvez cependant appeler un Controlleur secondaire depuis une vue (par exemple pour charger le menu) en utilisant:
pzEngine::getController('nom_controller', 'nom_action', 'variable', PZ_CONTROLLER_LOAD_VIEW);

Si vous remplacez PZ_CONTROLLER_LOAD_VIEW par PZ_CONTROLLER_LOAD_SILENT, le controlleur se chargera sans retourner d'output.
Ceci est utile si vous souhaitez utiliser des fonctionnalités spécifiques à un controlleur, sans pour autant vouloir le charger visuellement.

pzi18n

La classe pzi18n vous permet d'ajouter des balises {i18n:MA_VARIABLE} dans vos Vues, chose qui aura pour effet de remplacer la balise par MA_VARIABLE équivalente dans la langue de l'utilisateur (pas d'auto-détection pour le moment).

pzGeoip

Cette classe permet de Géo-localiser vos visiteurs selon leur adresses ip.
Elle nécessite une table MySQL? mise à jour par un script placé dans puzzle/cron/.
Il est conseillé de mettre à jour la table deux fois par mois pour des résultats corrects.

Les Classes "Framework"

Celles-ci sont utilisable et chargables par getClass().


- pzSession

• pzDatabase
• pzUser*
• pzUsergroup*
• pzBrowserinfo

(*) ces classes sont encore en développement.

pzDatabase

Cette classe fournit une API simple et efficace pour MySQL?.
Elle gère les connexions, les requêtes et quelques erreurs.

pzBrowserinfo

Cette classe retourne des informations détaillées sur le navigateur de vos visiteurs.
Utile pour faire des statistiques.

pzSession

Cette classe est la plus aboutie du Framework.
Elle s'occupe des sessions utilisateurs, sans utiliser session_start().
Vous pouvez la configurer en auto-load (voir fichier de configuration) pour gérer automatiquement les sessions.

Sites utilisant Puzzle

Des Nichoirs Dans La Plaine : http://www.desnichoirsdanslaplaine.fr/

Auteur

Puzzle à été développé par Julien Ballestracci au cours de sa mission au Réseau Ecole & Nature.
Vous pouvez me contacter par mail: julien [at] nitronet [point] org

---