Développer un module
Ce document décrit la méthode recommandée pour créer un module compatible avec Portix 3 0.8.2.
L’objectif est de développer une fonctionnalité autonome sans modifier inutilement le noyau.
1. Définir le domaine du module
Avant d’écrire du code, définir clairement :
- ce que fait le module ;
- ce qu’il stocke ;
- ses pages publiques ;
- ses pages d’administration ;
- qui peut les administrer ;
- s’il intervient dans la navigation ;
- s’il nécessite des URL courtes.
Exemple :
Module : Catalogue
Fonctions :
- créer des fiches ;
- les classer ;
- publier/dépublier ;
- afficher le catalogue publiquement.
Accès administration :
- rédacteur et administrateur.
Pages :
catalogue.html
catalogue-categorie-guitares.html
Admin-catalogue.html
2. Choisir un préfixe
Chaque module possède un préfixe.
Exemple :
catalogue
Il sert notamment au routage :
catalogue.html
Admin-catalogue.html
Évitez les noms pouvant entrer en conflit avec :
accueil
admin
install
index
login
disconnect
personnal
ou avec le préfixe d’un module existant.
3. Créer le dossier
Créer :
var/modules/catalogue/
Structure recommandée :
catalogue/
├── desc.xml
├── index.php
├── config.php
│
├── database/
│ ├── catalogue_categories/
│ │ └── desc.csv
│ └── catalogue_items/
│ └── desc.csv
│
├── lang/
│ ├── fr.php
│ └── en.php
│
├── src/
│ ├── CatalogueRepository.php
│ └── CatalogueAdminController.php
│
└── templates/
├── index.tpl
├── admin-list.tpl
└── admin-form.tpl
Ajoutez uniquement les fichiers nécessaires.
4. Créer le manifeste
Créer :
desc.xml
Exemple :
<?xml version="1.0" encoding="UTF-8"?>
<modules>
<Name>Catalogue</Name>
<Prefix>catalogue</Prefix>
<Type>module</Type>
<Priority>10</Priority>
<DefLang>fr</DefLang>
<Path>catalogue</Path>
<Enabled>1</Enabled>
<AdminAccess>editor</AdminAccess>
<SchemaFormat>desc-csv</SchemaFormat>
</modules>
Champs principaux
Name
Nom affiché :
<Name>Catalogue</Name>
Prefix
Identifiant utilisé pour les routes :
<Prefix>catalogue</Prefix>
Utiliser uniquement lettres, chiffres et _.
Type
Pour un module fonctionnel ordinaire :
<Type>module</Type>
Priority
Ordre relatif :
<Priority>10</Priority>
DefLang
Langue de secours :
<DefLang>fr</DefLang>
Path
Doit correspondre au nom du dossier :
<Path>catalogue</Path>
Enabled
État initial :
<Enabled>1</Enabled>
AdminAccess
Valeurs disponibles :
none
editor
admin
Pour du contenu éditorial :
<AdminAccess>editor</AdminAccess>
Pour une configuration sensible :
<AdminAccess>admin</AdminAccess>
SchemaFormat
Si le module possède des tables :
<SchemaFormat>desc-csv</SchemaFormat>
Sinon :
<SchemaFormat>none</SchemaFormat>
5. Créer le schéma SQLite
Un module ne doit pas modifier directement le Migrator du noyau pour ajouter ses propres tables.
Les tables sont décrites dans :
database/
Chaque dossier représente une table.
Exemple :
database/catalogue_items/desc.csv
Contenu :
id; numeric; notnull; ; ; ; primary; ;
category_id; numeric; null; ; ; index; ; catalogue_categories.id; setnull
title; text; notnull; ; ; index; ; ;
slug; text; notnull; ; unique; index; ; ;
body; text; notnull; ; ; ; ; ;
status; text; notnull; draft; ; index; ; ;
created_at; date; notnull; ; ; ; ; ;
updated_at; date; notnull; ; ; index; ; ;
6. Format desc.csv
Les colonnes sont :
1. nom
2. type
3. nullabilité
4. valeur par défaut
5. unique
6. index
7. clé primaire
8. référence éventuelle
9. règle de suppression
Types disponibles :
numeric
bool
date
text
Nullabilité :
notnull
null
Options :
unique
index
primary
Référence :
autre_table.colonne
Suppression :
restrict
cascade
setnull
Les noms de tables et colonnes doivent utiliser :
- lettres minuscules ASCII ;
- chiffres ;
- _.
Ils doivent commencer par une lettre.
7. Relations
Exemple :
category_id; numeric; null; ; ; index; ; catalogue_categories.id; setnull
signifie :
catalogue_items.category_id
↓
catalogue_categories.id
avec :
ON DELETE SET NULL
Une table ne peut référencer qu’une table appartenant au même schéma de module.
La colonne cible doit être primaire ou unique.
8. Évolutions du schéma
L’installation du schéma est conçue pour être idempotente.
Réinstaller un module peut notamment :
- conserver ses données ;
- conserver ses tables ;
- ajouter de nouvelles colonnes.
Il ne faut pas compter sur l’installation normale pour :
- supprimer une colonne ;
- supprimer automatiquement des données ;
- prendre possession d’une table existante.
Les migrations destructives doivent rester exceptionnelles et explicitement conçues comme telles.
9. Repository
Placez les requêtes SQL dans une classe dédiée.
Exemple :
<?php
declare(strict_types=1);
namespace PortixModule\Catalogue;
use PDO;
final class CatalogueRepository
{
public function __construct(
private readonly PDO $pdo
) {
}
public function published(): array
{
$statement = $this->pdo->prepare(
'SELECT id, title, slug, body
FROM catalogue_items
WHERE status = :status
ORDER BY title'
);
$statement->execute([
'status' => 'published',
]);
return $statement->fetchAll(PDO::FETCH_ASSOC);
}
}
Dans la branche 0.7, charger explicitement la classe :
require_once './var/modules/catalogue/src/CatalogueRepository.php';
10. Page publique
Créer :
index.php
Exemple minimal :
<?php
declare(strict_types=1);
require_once './var/modules/catalogue/src/CatalogueRepository.php';
$repository = new \PortixModule\Catalogue\CatalogueRepository(
$database->connection()
);
$template->setSlot(
'main',
'./var/modules/catalogue/templates/index.tpl'
);
$template->set(
'catalogue_title',
$translator->text('catalogue_title')
);
$items = $repository->published();
$template->set(
'catalogue_has_items',
$items === [] ? '0' : '1'
);
foreach ($items as $item) {
$template->addRow('catalogueitem', [
'title' => (string) $item['title'],
'slug' => (string) $item['slug'],
]);
}
$pageMetadata->define(
$translator->text('catalogue_title'),
'',
'catalogue.html'
);
11. Template public
Créer :
templates/index.tpl
Exemple :
<header class="content-heading">
<h1>{{ catalogue_title }}</h1>
</header>
{% if catalogue_has_items == "0" %}
<p role="status">Aucun élément publié.</p>
{% endif %}
{% if catalogue_has_items == "1" %}
<div class="catalogue-list">
{% for catalogueitem in catalogueitem %}
<article>
<h2>
<a href="catalogue-{{ catalogueitem.slug }}.html">
{{ catalogueitem.title }}
</a>
</h2>
</article>
{% endfor %}
</div>
{% endif %}
Toutes les variables utilisées doivent être initialisées.
12. Traductions
Créer :
lang/fr.php
Exemple :
<?php
$_LANG = array_merge($_LANG, [
'catalogue_title' => 'Catalogue',
'catalogue_new' => 'Nouvelle fiche',
'catalogue_save' => 'Enregistrer',
]);
Créer également :
lang/en.php
avec les mêmes clés.
Dans PHP :
$translator->text('catalogue_title');
Évitez les textes d’interface écrits directement dans les contrôleurs.
13. Administration
Créer :
config.php
Idéalement, ce fichier ne contient que l’initialisation.
Exemple :
<?php
declare(strict_types=1);
require_once './var/modules/catalogue/src/CatalogueRepository.php';
require_once './var/modules/catalogue/src/CatalogueAdminController.php';
$repository = new \PortixModule\Catalogue\CatalogueRepository(
$database->connection()
);
(new \PortixModule\Catalogue\CatalogueAdminController(
$repository,
$translator
))->handle(
$template,
$argument,
$user
);
Le véritable traitement est ainsi isolé dans une classe.
14. Contrôleur d’administration
Le contrôleur doit :
- analyser l’action ;
- vérifier la méthode HTTP ;
- vérifier les droits ;
- valider les données ;
- vérifier le CSRF ;
- appeler le repository ;
- sélectionner le template.
Évitez de placer de grandes quantités de logique directement dans config.php.
15. Écriture de données
Pour une action modifiant la base :
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
// refuser ou afficher le formulaire
}
Puis vérifier le CSRF avec les mécanismes Portix.
Toute donnée extérieure doit être :
- récupérée ;
- normalisée ;
- validée ;
- transmise à une requête préparée.
16. Suppression
Une suppression ne doit jamais être déclenchée par un simple lien GET.
Utiliser :
POST
+
CSRF
+
contrôle du rôle
+
confirmation
Pour une opération destructive importante, privilégier le rôle Administrateur.
17. Contenu HTML riche
Si le module accepte du contenu WYSIWYG, ne pas l’afficher directement.
Utiliser le sanitizer :
PortixHtmlSanitizer::clean($body)
puis seulement :
\Portix\View\Html::trusted($cleanBody)
Html::trusted() n’est pas un sanitizer.
Il indique uniquement au moteur que le HTML fourni est déjà digne de confiance.
18. URL courtes facultatives
Supposons que le module veuille publier :
ma-fiche.html
au lieu de :
catalogue-page-ma-fiche.html
Ajouter au manifeste :
<PublicRouteResolver>routes.php</PublicRouteResolver>
Créer :
routes.php
Exemple :
<?php
declare(strict_types=1);
require_once __DIR__ . '/src/CatalogueRepository.php';
return static function (\PDO $pdo, string $slug): ?array {
$repository = new \PortixModule\Catalogue\CatalogueRepository($pdo);
$item = $repository->findPublishedBySlug($slug);
if ($item === null) {
return null;
}
return [
'catalogue',
'page',
$slug,
];
};
Le résolveur doit être rapide et ne reconnaître que des contenus réellement publiés.
19. Contribution à la navigation
Un module peut également déclarer :
<PublicNavigation>navigation.php</PublicNavigation>
Ce fichier peut ajouter ses propres éléments au menu public.
Il reçoit déjà :
- le template ;
- la route ;
- la base ;
- le traducteur.
Le module doit rester responsable de sa propre hiérarchie.
20. Métadonnées
Utilisez :
$pageMetadata
pour définir :
- titre ;
- description ;
- adresse canonique ;
- type de page.
Exemple :
$pageMetadata->define(
$item['title'],
$item['body'],
$item['slug'] . '.html',
'article'
);
Évitez de générer vous-même des balises <meta> dans un module.
21. Accessibilité
Un module livré avec Portix 3 doit respecter la cible WCAG 2.2 AA du projet.
En particulier :
- HTML sémantique ;
- labels de formulaire ;
- boutons identifiables ;
- titres structurés ;
- messages d’état accessibles ;
- navigation clavier ;
- focus visible ;
- alternatives aux actions de glisser-déposer ;
- pas de tabindex positif ;
- pas d’événements JavaScript intégrés dans le HTML.
22. Installer le module
Depuis la racine du projet :
& "C:\xampp\php\php.exe" tools\install_module.php var\modules\catalogue
Résultat attendu :
Module installé : Catalogue
Tables du module : catalogue_categories, catalogue_items
L’installation doit pouvoir être répétée sans perte de données.
23. Tester la réinstallation
Exécutez la commande une seconde fois :
& "C:\xampp\php\php.exe" tools\install_module.php var\modules\catalogue
Puis vérifiez que :
- les données existantes sont conservées ;
- aucune table n’est dupliquée ;
- les nouvelles colonnes éventuelles sont correctement ajoutées.
24. Tests spécifiques au module
Un module important devrait disposer de son propre smoke test.
Par exemple :
tools/smoke_test_catalogue.php
Il doit idéalement vérifier :
- installation du schéma ;
- création d’un élément ;
- modification ;
- recherche ;
- publication ;
- suppression ;
- contraintes SQL ;
- permissions ;
- routage spécifique.
25. Validation complète
Après développement :
& "C:\xampp\php\php.exe" tools\validate_release.php --http=http://localhost/P3
La validation complète doit rester verte.
Tester ensuite manuellement :
- page publique ;
- administration ;
- rôle Administrateur ;
- rôle Rédacteur ;
- visiteur anonyme ;
- formulaire ;
- erreurs de validation ;
- activation/désactivation du module ;
- navigation clavier.
26. Ce qu’un module ne doit pas faire
Un module ne doit normalement pas :
- modifier index.php ;
- ajouter ses tables au Migrator général ;
- accéder aux tables d’un autre module sans contrat explicite ;
- utiliser une base SQLite séparée sans nécessité particulière ;
- construire du SQL avec des valeurs utilisateur concaténées ;
- produire directement des mots de passe ou secrets dans les logs ;
- stocker des fichiers privés dans un dossier public ;
- contourner le système de rôles ;
- produire du HTML non nettoyé avec Html::trusted() ;
- ajouter une dépendance au noyau lorsqu’une fonction peut rester locale au module.
27. Organisation recommandée
Pour un module conséquent :
index.php
↓
Repository + services
↓
Template
config.php
↓
AdminController
↓
Repository + services
↓
Template
Le but est de garder :
index.php
config.php
aussi petits que possible.
Cette organisation rendra également le module plus facile à migrer lorsque Portix 3 remplacera ses contrôleurs procéduraux dans la branche 0.8.
28. Checklist avant livraison
Avant de considérer un module comme terminé :
- desc.xml valide ;
- préfixe unique ;
- droits AdminAccess corrects ;
- traductions FR/EN ;
- schéma propre au module ;
- installation idempotente ;
- PDO préparé partout ;
- CSRF sur les écritures ;
- POST sur les suppressions ;
- vérification des rôles ;
- HTML échappé ;
- contenu riche nettoyé ;
- templates sans variable manquante ;
- pages accessibles au clavier ;
- activation/désactivation testée ;
- réinstallation testée ;
- validation complète Portix 3 réussie.
Un module qui respecte cette checklist peut être considéré comme correctement intégré à l’architecture actuelle de Portix 3.
29. Documentation fonctionnelle
Chaque nouvelle fonction ou évolution ergonomique d’un module doit mettre à jour sa documentation fonctionnelle, ses traductions et ses tests dans la même livraison. Si le changement concerne l’utilisation quotidienne, mettre aussi à jour le guide Administrateur ou Rédacteur de src/Installation/default-content.json. Les conventions générales sont documentées dans les guides Portix 3 installés en base de données.
Déclarer la version du module
Tout module distribué doit déclarer une version lisible par le gestionnaire de modules :
<Version>1.0.0</Version>
Cette valeur se place dans desc.xml. Si le paquet contient également MODULE-VERSION, les deux valeurs doivent être identiques.
Le numéro de version ne doit pas exister uniquement dans le nom du fichier ZIP : le gestionnaire de modules doit pouvoir le lire après installation.
Templates stricts
Le moteur de templates de Portix est strict : toute variable utilisée par un template doit être initialisée avant le rendu, y compris les libellés de traduction. Une nouvelle vue doit donc être contrôlée en recherchant l’ensemble de ses variables {{ ... }} et des lignes utilisées dans ses boucles.