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 :

  1. la vérification de la version PHP ;
  2. le positionnement du dossier racine ;
  3. le chargement des services historiques encore nécessaires ;
  4. la lecture de la configuration ;
  5. la configuration du niveau d’erreur ;
  6. l’analyse de la requête HTTP ;
  7. le démarrage sécurisé de la session ;
  8. la création de la connexion SQLite ;
  9. 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 :

  1. respecter l’architecture actuelle ;
  2. isoler autant que possible sa logique dans des classes ;
  3. limiter le code présent dans index.php et config.php ;
  4. é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.