Organisation des dossiers et fichiers d'un projet Adventy

Les types de dossier

Structure de fichiers
Figure 1

Les dossiers sont organisés :

  1. d'abord de façon technique : il existe 2 types de fichiers techniques. Le premier commence par le caractère "_", indiquant un dossier utilisé exclusivement par le framework (ex : _cache, _log). Le second (sans le préfixe "_") sert à organiser les fichiers par type technique (ex : applicatio/aop, application/model) ;
  2. puis par dossier métier : ce type de dossier est créé par le développeur, à l'intérieur des dossiers techniques.

Les dossiers à la racine

  1. /_cache : dossier utilisé pour la gestion du cache. Par exemple, les pages statiques sont mises en cache, et il en est de même pour le résultat de certaines requêtes SQL. Cette pratique permet de répondre plus rapidement à la requête de l'utilisateur, mais également d'alléger les charges du moteur PHP et de la base de données ;
  2. /_log : ce dossier contient les logs d'erreur ou trace. Cette fonctionnalité peut être désactivée dans le fichier de configuration de l'application. Ce dossier est utile lorsque le développeur n'a pas accès au fichier de log Apache (ex : /var/log/apache2/error.log), ou s'il souhaite créer des traces lors d'un débogage.
  3. /application : dossier de l'application qui est constitué de dossiers techniques, et qui eux-même contiennent des dossiers techniques ou métiers. Seuls les dossiers métiers peuvent contenir des fichiers. Ces derniers sont donc organisés par type technique, puis par métier ;
  4. /public : c'est un dossier dans lequel les ressources sont publiques et accessibles directement par l'URL, telles que les images, les feuilles de style, les scripts Javascript, les fichiers XML et autres fichiers de type texte.

Les dossiers et fichiers de /application

A première vue, cela peut paraître bien compliqué en raison du nombre assez important de dossiers, mais cela est tout autre. Les fichiers sont regroupés par type, et ce type est indiqué par le nom de dossier comme suit :

/application/aop
Le dossier aop réunit tous les tisseurs d'aspects. Il existe au plus un fichier de type tisseur d'aspects par ressource (requête http ou action). Ce type de fichier est facultatif. S'il n'est pas déclaré, alors la ressource sera rattachée à un tisseur d'aspect par défaut. L'extension de fichier utilisée est *.aop.php.
/application/configuration
Ce dossier contient tous les fichiers *.cfg.php pour la configuration de l'application. Ce sont généralement des déclarations de variables d'environnement que l'on y trouve.
/application/exception
C'est dans le dossier exception que le développeur pourra créer des exceptions personnalisées en plus des exceptions du framework Adventy. L'extension de ce type de fichier est *.class.php.
/application/form
Le dossier form regroupe la déclaration des paramètres passés aux actions, soit dans l'URL (méthode GET), soit à l'aide d'un formulaire (méthode POST). Ces déclarations permettent d'automatiser le contrôle technique (format, type, longueur) des données en entrée. L'extension utilisée pour ces fichiers est *.form.php.
/application/i18n
En cas de site multilingue, toutes les traductions devront être placées dans le dossier i18n. L'extension de fichier est de la forme *.<isoCode2>.i18n.php, où isoCode2 est le code de langue en 2 caractères minuscule (ex : fr, en).
/application/library
Il est possible de créer des classes utilitaires (*.class.php), ou d'intégrer des bibliothèques externes. C'est le rôle du dossier library de centraliser tout cela.
/application/meta
En SEO, il est important de renseigner au minimum le titre (balise title) et la description (balise meta description) des pages. Le dossier meta regroupe ces déclarations et d'autres aussi, avec l'extension de fichier *.meta.php.
/application/model
Le dossier model est divisé en 2 sous-dossiers :
Le premier est le sous-dossier bo (Business Object ou objet métier) qui contient les classes métiers dans lesquelles les actions sont implémentées. Ces classes sont suffixées par Bo et ont pour extension de fichier *.class.php. Les méthodes qui y sont développées correspondent aux aspects de l'AOP.
L'autre sous-dossier est dao (Data Access Object ou objet d'accès aux données). Ce dossier regroupe toutes les classes de suffixes Dao. Les accès à la base de données y sont implémentés. L'extension de fichier utilisée est aussi *.class.php. Une classe DAO est associé par défaut à une table de base de données.
/application/reference
Le dossier reference regroupe les données de référence, à l'image d'une table de référence dans une base de données. Les fichiers qui y sont présents ont l'extension *.reference.php. Ces données désignent une liste finie de données (ex : civilité).
/application/template
Ce dossier contient tous les modèles utilisés par l'application, tels que les templates de pages, des portions de code ou de texte, des modèles d'emails, etc. L'extension de ce type de fichier est *.template.php.
/application/view
La vue peut être décomposée par type de vue. Il en est déduit les sous-dossiers techniques suivants :
  1. page : ce dossier regroupe la vue des pages (corps de page en HTML). Les fichiers qui y sont enregistrés ont l'extension *.body.php.
  2. event : comme le dossier page, le dossier event stocke des vues, mais ce sont des vues liées à des requêtes de type AJAX générées par un évènement, comme par exemple le clic sur un bouton. L'extension pour ce type de fichier est *.body.php.
  3. ws : ce dossier y enregistre les vues des web services. L'extension de ces fichiers est aussi *.body.php.
  4. css : le sous-dossier css contient les feuilles de style des pages. L'extension de fichier est *.css.php.
  5. js : les scripts de page sont placés dans le dossier js. Ces fichiers portent l'extension *.js.php.

L'utilisation de ces dossiers sera expliquée plus en détail tout au long de la documentation.

Les dossiers et fichiers de /public

/public/image
Comme son nom l'indique, ce dossier réunit toutes les images de l'application (ex : *.jpg, *.png).
/public/css
Tous les fichiers CSS doivent être placés dans le dossier css. L'extension de ces fichiers est *.css.
/public/js
Le dossier js regroupe tous les fichiers Javascript avec l'extension *.js.
/public/robot
le dossier robot est destiné aux applications externes. Ces dernières viennent y lire des ressources telles que le sitemap, le RSS... Les fichiers peuvent être de type divers, en *.xml (ex : sitemap.xml, BingSiteAuth.xml), ou en *.html (ex : googlec3850ccd0af1a2c3.html). Ce dossier n'a d'utilité que pour les sites de type internet.