Portix 3 — Structure et fonctionnement
Ce document décrit l’architecture technique de Portix 3 0.8.2, le cycle d’une requête, le stockage des données, le fonctionnement des modules et les principales conventions à respecter lors du développement.
Portix 3 nécessite PHP 8.2 minimum et utilise une base SQLite unique accessible par PDO.
La branche 0.7 constitue une architecture modernisée mais encore transitoire : certaines fonctions historiques ont déjà été remplacées par des services et contrôleurs modernes, tandis que plusieurs modules utilisent encore des points d’entrée procéduraux. Cette situation doit être prise en compte lors du développement.
1. Principes généraux
Portix 3 repose sur quelques principes simples :
- un seul point d’entrée HTTP ;
- une initialisation centralisée ;
- une base SQLite native ;
- PDO et requêtes préparées ;
- un noyau distinct des modules ;
- un système de templates avec échappement HTML automatique ;
- des modules capables de posséder leur propre schéma de données ;
- une séparation entre site public et administration ;
- deux rôles seulement :
- Administrateur ;
- Rédacteur ;
- des tests automatisés intégrés au projet.
Les modules doivent autant que possible rester autonomes et ne pas nécessiter de modification du noyau.
2. Organisation générale
La structure principale est la suivante :
Portix3/
│
├── index.php
├── install.php
├── VERSION
│
├── bootstrap/
│ ├── app.php
│ └── autoload.php
│
├── src/
│ ├── Configuration/
│ ├── Controller/
│ ├── Core/
│ ├── Domain/
│ ├── Http/
│ ├── Infrastructure/
│ ├── Installation/
│ ├── Mail/
│ ├── Module/
│ ├── Observability/
│ ├── Repository/
│ ├── Security/
│ ├── Seo/
│ ├── Storage/
│ ├── Support/
│ └── View/
│
├── includes/
│ ├── engine.php
│ └── class/
│
├── database/
│ └── portix2.sqlite
│
├── sessions/
├── tmp/
│
├── var/
│ ├── admin/
│ ├── editor/
│ ├── lang/
│ ├── modules/
│ ├── private/
│ ├── sys/
│ ├── templates/
│ └── uploads/
│
└── tools/
3. Le point d’entrée
Toutes les requêtes normales arrivent sur :
index.php
Ce fichier doit rester minimal.
Son rôle consiste essentiellement à charger :
bootstrap/app.php
puis à exécuter l’application.
La logique métier ne doit pas être ajoutée directement dans index.php.
4. Bootstrap
Le bootstrap prépare l’environnement commun à toutes les requêtes.
La classe principale est :
Portix\Core\Bootstrap
Elle effectue notamment :
- la vérification de la version PHP ;
- le positionnement du dossier racine ;
- le chargement des services historiques encore nécessaires ;
- la lecture de la configuration ;
- la configuration du niveau d’erreur ;
- l’analyse de la requête HTTP ;
- le démarrage sécurisé de la session ;
- la création de la connexion SQLite ;
- la création de l’objet Application.
Le bootstrap ne doit pas dépendre d’un module particulier.
5. Chargement des classes
Les classes modernes du noyau utilisent le namespace :
Portix\
Le chargeur PSR-4 minimal associe par exemple :
Portix\Http\Request
à :
src/Http/Request.php
Composer peut être utilisé pour le développement et les tests, mais il n’est pas nécessaire à l’exécution du CMS.
Classes propres aux modules
Les classes appartenant directement à un module ne sont actuellement pas chargées automatiquement par le chargeur du noyau.
Le module Articles utilise par exemple :
namespace PortixModule\Articles;
et charge explicitement ses classes :
require_once './var/modules/articles/src/ArticleRepository.php';
Cette méthode reste la convention de la branche 0.7.
6. Cycle d’une requête
Une requête suit globalement ce parcours :
Navigateur
↓
Serveur Web
↓
index.php
↓
bootstrap/app.php
↓
Bootstrap
↓
Application
↓
Request
↓
Migrator / RepositoryRegistry
↓
includes/engine.php
↓
Module ou contrôleur
↓
Template
↓
HTML
7. Application
La classe :
Portix\Core\Application
coordonne le traitement général.
Elle :
- applique les en-têtes de sécurité ;
- crée un identifiant unique de requête ;
- vérifie que Portix est installé ;
- déclenche la migration du schéma du noyau si nécessaire ;
- initialise le limiteur persistant après cette migration ;
- crée les repositories ;
- détermine la route ;
- choisit le template public ou administratif ;
- initialise les métadonnées ;
- charge actuellement includes/engine.php ;
- affiche finalement le template.
Les erreurs non interceptées sont journalisées et produisent une page HTTP 500.
En production, les traces PHP détaillées ne sont pas envoyées au visiteur.
8. Routage
La requête est représentée par :
Portix\Http\Request
Les URL sont volontairement lisibles.
Exemples :
accueil.html
news.html
articles.html
Admin.html
Admin-articles.html
Une URL comportant plusieurs parties est découpée sur les tirets lorsque son préfixe correspond à un module connu.
Ainsi :
articles-categorie-documentation.html
peut produire :
[
'articles',
'categorie',
'documentation'
]
Le premier élément désigne le module.
Les éléments suivants servent d’action et de paramètres.
9. URL courtes
Portix 3 permet également à un module de reconnaître une adresse qui ne contient pas son préfixe.
Exemple :
installation-de-portix.html
au lieu de :
articles-page-installation-de-portix.html
Pour cela, le module peut déclarer un :
<PublicRouteResolver>routes.php</PublicRouteResolver>
Le résolveur recherche le contenu correspondant et retourne la route interne.
Exemple :
return static function (PDO $pdo, string $slug): ?array {
// recherche du contenu
return ['articles', 'page', $slug];
};
S’il ne reconnaît pas l’adresse :
return null;
Le noyau peut alors interroger un autre module.
10. Base de données
Portix 3 utilise :
database/portix2.sqlite
Le nom du fichier est encore historique mais le contenu est entièrement SQLite natif.
Le noyau utilise :
- PDO ;
- les exceptions PDO ;
- les requêtes préparées ;
- les transactions ;
- les clés étrangères ;
- PRAGMA user_version ;
- une table de migrations.
Les anciens mécanismes de stockage XML PortixDB ne font plus partie de Portix 3.
11. Repositories
Les accès SQL du noyau sont regroupés dans :
src/Repository/
Par exemple :
UserRepository
ModuleRepository
NewsRepository
MenuRepository
ContactRepository
DownloadRepository
InsightRepository
Ils sont regroupés par :
RepositoryRegistry
Un repository :
- reçoit une connexion PDO ;
- effectue les requêtes SQL ;
- retourne les données ;
- ne doit pas produire de HTML.
Les requêtes utilisant des valeurs extérieures doivent être préparées.
12. Schéma du noyau et schéma des modules
Le schéma général contient notamment :
users
modules
menu_items
news
rate_limits
La table rate_limits appartient au noyau : elle conserve uniquement des clés pseudonymisées et les compteurs temporaires nécessaires à la protection de la connexion, de la récupération du mot de passe et du formulaire Contact.
Les nouveaux domaines fonctionnels doivent, lorsqu’ils sont autonomes, posséder leurs propres tables de module.
Par exemple Articles possède :
articles
article_categories
article_settings
Ces tables se trouvent physiquement dans la même base SQLite, mais leur propriété est enregistrée dans :
module_schema_tables
Un module ne peut pas prendre possession d’une table appartenant au noyau ou à un autre module.
13. Modules
Les modules sont stockés dans :
var/modules/
Exemples :
articles/
contact/
download/
insights/
menu/
news/
UserZone/
Un module typique possède :
module/
├── desc.xml
├── index.php
├── config.php
├── lang/
├── templates/
├── src/
└── database/
Tous ces éléments ne sont pas obligatoires.
14. desc.xml
Le fichier :
desc.xml
constitue actuellement le manifeste du module.
Exemple :
<?xml version="1.0" encoding="UTF-8"?>
<modules>
<Name>Articles</Name>
<Prefix>articles</Prefix>
<Type>module</Type>
<Priority>5</Priority>
<DefLang>fr</DefLang>
<Path>articles</Path>
<Enabled>1</Enabled>
<AdminAccess>editor</AdminAccess>
<SchemaFormat>desc-csv</SchemaFormat>
<PublicNavigation>navigation.php</PublicNavigation>
<PublicRouteResolver>routes.php</PublicRouteResolver>
</modules>
Il définit notamment :
- le nom ;
- le préfixe d’URL ;
- le type ;
- la priorité ;
- la langue par défaut ;
- le dossier ;
- l’état initial ;
- les droits administratifs ;
- le type de schéma ;
- une éventuelle contribution au menu ;
- un éventuel résolveur de routes.
Ce manifeste sera probablement remplacé par un système plus moderne dans une future branche 0.8.
15. Entrée publique d’un module
Pour une route correspondant à un module actif, Portix charge :
var/modules/nom/index.php
Le module reçoit déjà le contexte nécessaire, notamment :
$database
$template
$argument
$translator
$pageMetadata
$user
Il ne doit donc pas redémarrer lui-même Portix.
Un module choisit généralement son template avec :
$template->setSlot(
'main',
'./var/modules/exemple/templates/index.tpl'
);
16. Administration d’un module
Lorsqu’un module possède :
config.php
il peut disposer d’une interface d’administration.
L’adresse principale est généralement :
Admin-prefix.html
Exemple :
Admin-articles.html
Le niveau d’accès est défini par :
<AdminAccess>editor</AdminAccess>
Valeurs reconnues :
none
editor
admin
editor autorise administrateurs et rédacteurs.
admin réserve l’écran aux administrateurs.
17. Templates
Portix utilise :
Portix\View\Template
Une variable est affichée avec :
{{ title }}
et fournie par PHP avec :
$template->set('title', $title);
Principe important
Une variable absente provoque une erreur.
Le développeur doit donc explicitement initialiser toutes les variables utilisées par le template.
Cette règle évite qu’un défaut soit silencieusement masqué.
18. Échappement HTML
Les valeurs ordinaires sont automatiquement échappées.
Ainsi :
$template->set('name', '<script>');
ne produit pas de script exécutable.
Un module ne doit utiliser du HTML explicite que lorsque celui-ci a été produit ou nettoyé volontairement :
Portix\View\Html::trusted($html)
Le contenu riche provenant d’un utilisateur doit d’abord passer par le sanitizer de Portix.
19. Conditions et boucles
Conditions :
{% if published == "1" %}
<p>Publié</p>
{% endif %}
Boucles :
{% for item in items %}
<article>{{ item.title }}</article>
{% endfor %}
Les lignes sont fournies avec :
$template->addRow('items', [
'title' => $title,
]);
20. Traductions
Les traductions globales se trouvent dans :
var/lang/
Les traductions d’un module se trouvent dans :
var/modules/module/lang/
Exemple :
$_LANG = array_merge($_LANG, [
'catalogue_title' => 'Catalogue',
]);
Elles sont récupérées avec :
$translator->text('catalogue_title');
Une fonctionnalité distribuée doit normalement prévoir au minimum les langues actuellement supportées par Portix.
21. Sécurité
Les conventions suivantes sont obligatoires lors d’un développement.
SQL
Utiliser PDO et des requêtes préparées.
Ne jamais construire une requête en concaténant directement une valeur fournie par l’utilisateur.
Formulaires
Les opérations de modification doivent utiliser un jeton CSRF.
Les points d’entrée exposés aux abus utilisent le limiteur SQLite du noyau. Il doit être initialisé uniquement après la migration. Un quota Contact n’est consommé qu’après validation du formulaire.
Suppression
Une suppression doit :
- utiliser POST ;
- vérifier le rôle ;
- vérifier le CSRF ;
- demander une confirmation explicite dans l’interface.
HTML
Le contenu utilisateur est échappé par défaut.
Le contenu HTML riche doit être désinfecté avant utilisation de Html::trusted().
Fichiers
Les données privées ne doivent pas être placées dans un dossier accessible directement par HTTP.
Le stockage privé se trouve notamment sous :
var/private/
22. Site public et administration
Portix distingue clairement deux interfaces.
Public
Le site utilise :
var/templates/modern/
Administration
L’administration utilise :
var/admin/
Le tableau de bord constitue le point central.
L’interface distingue également :
- gestion éditoriale ;
- administration/configuration.
Un nouveau module doit respecter cette séparation.
23. Validation
Le projet possède une suite automatisée.
La commande principale est :
& "C:\xampp\php\php.exe" tools\validate_release.php --http=http://localhost/P3
Elle vérifie notamment :
- PHP ;
- extensions ;
- syntaxe ;
- base SQLite ;
- routage ;
- templates ;
- sécurité ;
- localisation ;
- schémas des modules ;
- services ;
- stockage ;
- ZIP ;
- installateur ;
- principales routes HTTP.
Un développement ne doit pas être considéré comme terminé si cette validation ne passe pas.
24. Architecture actuelle et future
La version 0.7 contient encore une couche procédurale importante dans :
includes/engine.php
Les modules comme Articles utilisent également encore :
index.php
config.php
comme points d’entrée procéduraux.
La feuille de route 0.8 prévoit notamment :
- des contrôleurs injectés pour les modules ;
- un manifeste de module moderne ;
- un véritable contrat de thème ;
- des composants de templates réutilisables ;
- davantage de tests unitaires et d’intégration.
Un nouveau développement 0.7 doit donc :
- respecter l’architecture actuelle ;
- isoler autant que possible sa logique dans des classes ;
- limiter le code présent dans index.php et config.php ;
- éviter de créer de nouvelles dépendances fortes envers engine.php.
Cela facilitera la migration ultérieure vers l’architecture 0.8.
25. Règle fondamentale
Lorsqu’une fonctionnalité peut être développée comme module sans modification du noyau, elle doit être développée comme module.
Le noyau doit rester responsable de :
- l’application ;
- le routage général ;
- l’authentification ;
- la sécurité ;
- le stockage commun ;
- le moteur de templates ;
- l’installation des modules.
Le module doit rester responsable de son propre domaine fonctionnel.
26. Comportements fonctionnels documentés
Le champ article_categories.is_visible contrôle uniquement la présence d’une branche dans les menus et listes. Les résolveurs conservent l’accès direct aux pages de catégorie et aux articles publiés ; ce champ ne constitue pas une autorisation.
Le contenu riche conserve les paragraphes, les sauts de ligne <br>, le format Small et les liens portant target="_blank" avec rel="noopener noreferrer". Le sanitizer reste la frontière obligatoire avant Html::trusted().
Les URL automatiques issues d’un nom sont contrôlées contre les slugs des menus, articles et actualités afin d’éviter les collisions.
La documentation fonctionnelle de Portix 3 est stockée dans la base de données et sa source d’installation se trouve dans src/Installation/default-content.json. Toute évolution fonctionnelle ou ergonomique doit modifier cette documentation et ses tests dans la même livraison.
Prévisualisation et métadonnées 0.7.2
Les aperçus éditoriaux transitent par SessionPreviewStore : un jeton aléatoire référence temporairement les données dans la session authentifiée, sans écriture dans la base. Les routes d’aperçu sont exclues du sitemap et reçoivent noindex,nofollow.
Le service de métadonnées produit désormais TechArticle pour les articles et NewsArticle pour les actualités, avec date de publication, date de modification, auteur, image et éditeur lorsqu’ils sont disponibles.
Métadonnées des catégories
La colonne article_categories.description est déclarée par le schéma du module Articles. CategoryMetadataSchema ajoute ce champ à une installation existante à la première ouverture de l’administration Articles, après un snapshot SQLite cohérent dans var/private/category-description-backups. Aucun shell n’est utilisé. La page publique utilise la description de sa propre catégorie et conserve la description générale si le champ est vide. Les entrées de corbeille antérieures restent restaurables.
Métadonnées spécifiques à l’accueil
Les réglages seo_home_title et seo_home_description restent facultatifs et sont conservés lors des envois provenant d’un formulaire ancien. Après le module public, Application appelle PageMetadata::configureHomePage uniquement sur la racine publique sans erreur HTTP. La canonique est alors la racine. Le titre HTML peut être distinct du titre éditorial utilisé par NewsArticle ou TechArticle. Le graphe JSON-LD contient un seul nœud WebSite avec name et url sur l’accueil, lorsque le nom et l’adresse du site sont disponibles ; ce nœud n’est pas ajouté aux pages intérieures.
Versions de modules
Le manifeste desc.xml peut déclarer une balise <Version>. Cette information appartient au module et doit être mise à jour à chaque release installable du module.
Les modules actuellement versionnés dans cette baseline comprennent notamment Affiliation 1.1.2, News 1.0.1 et Search 1.0.3.
Comportements récents
- les actualités peuvent être épinglées sur la première page ;
- Search peut utiliser un surlignage de repli lorsque le navigateur ne gère pas les fragments de texte ;
- Affiliation expose une administration centrée sur les produits ;
- la configuration générale possède des métadonnées SEO propres à l’accueil ;
- l’éditeur normalise plusieurs formes de tableaux reçues depuis le presse-papiers.
URL PHP inconnues
Les contrôleurs PHP publics autorisés restent explicitement déclarés. Une autre URL se terminant par .php, .phtml ou une variante PHP n’exécute jamais le fichier demandé : elle est routée vers P3 et reçoit une réponse 404 thémée.
Contrat formel de thème
Depuis 0.7.09, chaque thème public doit respecter le contrat de thème v1. Il doit notamment fournir index.tpl, menu.tpl, not-found.tpl, style.css et style.min.css, exposer les emplacements principaux attendus par P3, fournir la navigation et la page 404, et charger sa feuille CSS publique versionnée.
La commande php tools/validate_theme.php --all vérifie tous les thèmes distribués. Un thème particulier peut être contrôlé en indiquant son nom à la place de --all.
Formats visuels RC11
Quill utilise les objets portix-image pour conserver ensemble les métadonnées et la légende. Le stockage reste du HTML sémantique : figure, figcaption, th, hr, classes de formats et largeurs validées. La sanitisation serveur autorise uniquement les formats prévus et les couleurs sûres. Les cellules et les largeurs font partie du modèle Quill et de son historique.
Nettoyage des tests SQLite
Les tests de réinitialisation du mot de passe et de schéma modulaire exécutent leurs vérifications dans une fonction isolée. Les dépôts, instructions et connexions PDO sont ainsi libérés avant de supprimer les fichiers SQLite temporaires. Cette règle évite les erreurs de fin de test dues aux fichiers encore ouverts, notamment avec WAL, Windows et les runtimes WebAssembly.
Collage dans une cellule Quill
Le gestionnaire pasteTextInTableCell normalise les paragraphes collés dans une cellule existante en contenu inline et en sauts portix-break. Il conserve les formats inline et évite l’insertion de blocs Quill qui séparent un tableau en deux. Les collages de tableaux structurés conservent leur voie dédiée. Les opérations sont regroupées dans l’historique pour pouvoir être annulées ou rétablies en une étape.
Manifeste et paquet de thème
Le fichier var/templates/identifiant/theme.json déclare schema (1), id, name, version, kind (theme ou shared), contract (chaîne « 1 »), p3_min, p3_max (facultatif), php_min, requires (liste contenant éventuellement shared), variant_of (provenance facultative, sans héritage) et files (chemins relatifs associés à leur SHA-256). Le nom du dossier et id doivent correspondre. Les versions suivent une forme numérique, avec suffixe facultatif. La version initiale des thèmes de cette livraison est 0.1.0.
Un ZIP comporte un unique dossier identifiant/ contenant theme.json et exactement les fichiers déclarés. Les cinq fichiers contractuels index.tpl, menu.tpl, not-found.tpl, style.css et style.min.css doivent être suivis. Sont acceptés les modèles .tpl, CSS, JavaScript, SVG, images et polices déclarés ; PHP, chemins sortants, liens symboliques, racines multiples et fichiers non déclarés sont refusés. Limites : 12 Mio de ZIP, 25 Mio extraits et 1 000 entrées. Les originaux de travail inutilisés ne doivent pas être ajoutés.
ThemeManifest valide les métadonnées ; ThemeCatalog contrôle compatibilité et personnalisations ; ThemePackageManager prépare, vérifie, sauvegarde et remplace sous verrou. Les opérations administrateur utilisent POST, CSRF, jeton de session pour l’analyse et confirmation avant installation ou restauration. Les données temporaires et sauvegardes sont sous var/private/theme-packages. La protection HTTP de var/private doit rester active. Les paquets locaux n’utilisent aucun catalogue distant ni signature d’éditeur. Les tests smoke_test_theme_manifest.php et smoke_test_theme_packages.php font partie de validate_release.php.
Permissions des articles et schéma 8
La migration 7 vers 8 ajoute uniquement users.article_permissions avec un objet JSON vide par défaut. ArticlePermissions applique le profil commun et les exceptions de compte, contrôle la propriété, l’état publié et les catégories source et destination. Les vérifications s’appliquent aux listes, formulaires, aperçus et actions directes, côté serveur. La création et la modification des catégories, leur ordre et les réglages du menu restent réservés à l’administrateur. Le changement des droits incrémente auth_version pour révoquer les anciennes sessions. Les droits ne sont pas des contrôles de lecture sur les articles publics.
La page Admin-config-themes.html utilise les protections d’installation de thèmes existantes ; elle est reliée depuis Configuration. Six Cordes 0.1.1 distingue le sous-menu du haut et la navigation latérale : un groupe contenant uniquement des articles ne crée aucun cadre vide dans le haut, mais garde ses liens dans la colonne de navigation.