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 :

  1. récupérée ;
  2. normalisée ;
  3. validée ;
  4. 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.