Accès direct au contenu Accès direct à la navigation

Ce document développe les règles de codage, de rangement et de nommage de nos paquets.

Standards de programmation & règles de nommage

Afin de construire un code maintenable et comprehensible, nous essayons de suivre les règles standrads en usage :

- les standards de code PEAR
- les standards du PHP Framework Interoperability Group.

Sachant cela, les classes de nos paquets sont nommées et organisées selon une architecture facilitant l’utilisation de la classe standard SplClassLoader, si vous utilisez Composer pour charger nos paquets, tous les espaces de noms nécessaires sont chargés automatiquement avec l’autoloader généré par Composer. Dans ce cas, vous n’avez rien de plus à faire que de charger les classes en utilisant le mot-clé use.

Architecture

Une architecture standard de l’un de nos paquets PHP pourrait être la suivante :

    | composer.json
    | sami.config.PHP
    | phpunit.xml.dist
    | .travis.yml
    | README.md
    | LICENSE
    |
    | bin/
    | ---- binary-script.PHP
    | ---- binary-script.sh
    |
    | data/
    | ----- data-file.csv
    |
    | demo/
    | ----- demo-page.HTML
    |
    | doc/
    | ---- documentation-file.md
    |
    | config/
    | ---- config-file.ini
    |
    | phpdoc/
    | ------- automatic PHP documentation ...
    |
    | src/
    | ---- PackageNamespace/
    | ---------------------- classname.PHP
    |
    | tests/
    | ---- unit-tests.PHP
    |
    | user/
    | ----- user-config.ini
    | ----- UserClass.PHP
    |
    | var/
    | ---- variable-file.txt
    | ---- history.log
    |
    | www/
    | ---- assets/
    | ------------ script-file.js
    | ------------ styles-file.CSS
    | ---- index.PHP

Pour ceux qui connaissent les kernel Linux, nous suivons sensiblement la même architecture.

Toute dépendance externe, notre Moteur de Template interne ou tout autre paquet est stocké dans un répertoire ou sous-répertoire nommé vendor/ ; vous ne devez pas modifier ces contenus.

Tout fichier temporaire comme du cache ou tout autre fichier dépendant de l’environnement courant est stocké dans un répertoire ou sous-répertoire nommé tmp/. Tout fichier temporaire qui ne serait pas stocké dans l’un de ces répertoires DOIT être nommé tmp* (où l’astérisque peut être n’importe quoi). L’ensemble de ces fichiers sont exclus du contrôle de version et peuvent être supprimés sans incidence sur le projet (nous l’espèrons).

Présentation

- bin/ contient les scripts console, les installeurs ou updateurs automatiques et les scripts shell tiers ;

- data/ contient les fichiers de données (comme les CSV par exemple) ;

- demo/ contient les démonstration de nos paquets au format HTML ;

- doc/ contient des fichiers de documentation, le plus souvent au format Markdown ;

- config/ contient les fichiers de configuration ;

- src/ contient les sources PHP de l’application et les fichiers de template ;

- user/ est le répertoire accueillant toute surharge éventuelle des configurations ou templates (voyez la section Fallback system ci-dessous pour plus d’information) ;

- var/ contient les fichiers dits "variables" (ré-insriptibles) ;

- www/ doit être la racine (le DOCUMENT_ROOT) de l’hôte virtuel utilisé (tout ce qui est en dehors de ce répertoire n’est pas utilisé dans les rendus HTML).

Fallback system

Nos paquets sont construits, lorsque c’est possible et censé, pour autoriser l’utilisation à surcharger certaines variables de configuration ainsi que les templates utilisés pour la génération des pages.

Le principe est assez simple : tout fichier trouvé dans un répertoire user/XXX/ sera pris en priorité au fichier par défaut du paquet, où XXX est le chemin relatif du fichier original depuis la racine du paquet.