netslim-core/docs/DEVELOPMENT.md

Développement

Ce document sert de guide quotidien pour travailler sur netslim-core.

Démarrage local

Prérequis : PHP 8.4+, Composer, extensions pdo, pdo_sqlite, fileinfo, gd, json, mbstring, session, dom, simplexml.

composer install
composer qa

Ce que contient le dépôt

• Kernel/ : runtime, HTTP, persistence, mail, html, pagination, support
• Identity/ : authentification, utilisateurs et autorisation transverse
• Settings/ : paramètres applicatifs typés
• AuditLog/ : journal d'audit partagé
• Notifications/ : notifications et emails transactionnels
• Taxonomy/ : taxons réutilisables
• Media/ : médiathèque transverse

Le dépôt ne contient pas d'application concrète : c'est le socle partagé. Une application consommatrice fournit son propre config/modules.php, son point d'entrée HTTP, ses templates applicatifs et ses assets. Les répertoires runtime (var/, database/, public/media/) appartiennent toujours au projet consommateur, même quand le core est installé sous vendor/.

Où placer une modification ?

Backend

• Domain/ : entités, règles métier, contrats métier
• Application/ : cas d'usage, services applicatifs, commandes, ports
• Infrastructure/ : implémentations concrètes, PDO, stockage, mail, bindings DI
• UI/ : contrôleurs, request objects, templates, extensions Twig

Code transverse

Kernel/ reste limité au transverse et se découpe en sous-modules explicites : Runtime/, Http/, Persistence/, Mail/, Html/, Pagination/ et Support/. En cas d'hésitation, commencer dans le domaine concerné puis extraire vers Kernel à la deuxième vraie réutilisation.

Checklist avant d'ajouter quelque chose dans Kernel/Support

Valider les trois points suivants :

• ce code sert déjà à au moins deux domaines ou représente une primitive transverse évidente ;
• il ne dépend ni d'un domaine métier, ni de Slim, Twig, PSR-7 ou d'une implémentation d'infrastructure ;
• la PR met à jour à la fois la documentation et l'allow list des tests d'architecture.

Faire évoluer un domaine existant

Ordre recommandé :

1. adapter le contrat ou l'interface de service si nécessaire ;
2. décider si la modification reste une lecture simple ou mérite un UseCase + éventuelle Command ;
3. faire évoluer le repository ou le port technique ;
4. adapter le contrôleur et les vues sans court-circuiter le service applicatif ;
5. mettre à jour les tests et la documentation utile.

Ajouter un nouveau domaine

Créer systématiquement :

1. l'entité et les contrats du domaine ;
2. l'interface de service ;
3. le repository interface ;
4. l'implémentation Infrastructure/ ;
5. le contrôleur et les templates ;
6. Infrastructure/dependencies.php ;
7. UI/Http/Routes.php ;
8. <Domaine>Module.php ;
9. les tests dans tests/<Domaine>/.

Pour les frontières et dépendances autorisées, se reporter à ARCHITECTURE.md.

Vérifications avant push

composer test
composer stan
composer cs:check

Raccourci utile :

composer qa

Variables d'environnement et provisionnement

Le bootstrap du noyau requiert seulement l'environnement technique commun (comme APP_URL). Les variables ADMIN_* sont nécessaires quand une application active Identity et exécute le provisionnement initial du compte administrateur. Les variables MAIL_* deviennent nécessaires uniquement si l'application active Notifications et envoie réellement des emails transactionnels.

Quand netslim-core est installé via Composer, les chemins runtime détectent automatiquement la racine du projet consommateur pour les scripts CLI et les suites de tests qui n'appellent pas explicitement Bootstrap::create().