velcome / prestashop-module-creator
Générateur en ligne de commande pour créer et faire évoluer des modules PrestaShop 8.x / 9.x.
Package info
git.ohweb.fr/module/veprestashopmodulecreator.git
pkg:composer/velcome/prestashop-module-creator
Requires
- php: ^8.1
- nikic/php-parser: ^5.3
- symfony/console: ^6.4|^7.0
- symfony/filesystem: ^6.4.50|^7.4.23
- symfony/options-resolver: ^6.4|^7.0
- symfony/polyfill-mbstring: ^1.27
- symfony/yaml: ^6.4.50|^7.4.23
- twig/twig: ^3.27
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.80
- phpstan/phpstan: ^2.3.2
- phpunit/phpunit: ^10.5.62|^11.5.50
- smarty/smarty: ^4.5.7
- symfony/process: ^5.4.51|^6.4.33|^7.3.11
Suggests
- ext-zip: Requise par make:zip pour construire l'archive d'installation du module (contrôlée au lancement de la commande).
Provides
None
Conflicts
- symfony/string: <5.4.35 || >=6.0,<6.4.3 || >=7.0,<7.0.3
Replaces
None
README
Générateur en ligne de commande pour créer et faire évoluer des modules PrestaShop 8.0.0 → 9.x.
Le binaire ve-module crée le squelette d'un module, puis y ajoute contrôleurs, onglets, classes ObjectModel, gabarits et le reste, une commande à la fois. Le code généré cible PHP ≥ 8.1, est commenté en français et suit les règles de sécurité de PrestaShop : requêtes protégées, jetons comparés par hash_equals(), échappement Smarty, installation et désinstallation idempotentes.
Points forts
- Un module complet en une commande :
make:modulecrée la classe principale, lecomposer.json(autoload PSR-4), les fichiers de services et les protectionsindex.php. - Puis élément par élément : contrôleurs, onglets du back-office, classes ObjectModel, gabarits, page de configuration, routes, services, commandes console, assets, tests, scripts de mise à jour.
- Rien sans votre accord : en interactif, chaque commande montre son plan et demande confirmation ;
--dry-runsimule, un fichier existant n'est remplacé qu'avec--force, et chaque fichier PHP passephp -lavant d'être écrit. - Classe principale modifiée par l'AST (nikic/php-parser), jamais par remplacement de texte, y compris sur un module qui n'a pas été créé par l'outil.
- Journal PSR-3 intégré, sans dépendance à un autre module.
- Prêt pour Claude Code : agents Claude (
CLAUDE.md,.claude/agents/) et tests PHPUnit isolés danstools/phpunit/. - Rien de l'outil n'est livré :
tools/ve-module/ettools/phpunit/sont exclus de l'archive du module et fermés à l'accès web.
Prérequis
- PHP ≥ 8.1 et Composer 2.
- PrestaShop 8.0.0 → 9.x pour installer les modules générés (l'outil lui-même n'en a pas besoin).
- Facultatif : Node.js
^22.18.0 || >=24.11.0et npm pour la compilation des assets (make:assets).
Installation
Le package s'installe dans chaque module, dans un dossier isolé : tools/ve-module/, avec son propre tools/ve-module/composer.json et son propre vendor/. Le binaire, tools/ve-module/vendor/bin/ve-module, se lance depuis la racine du module.
Jamais de
composer requiredu package à la racine du module, ni d'installation globale. PrestaShop charge levendor/autoload.phpdes modules (PrestaShop 8 celui de tout module actif, PrestaShop 9 celui de tout module installé, même désactivé) : le package et ses dépendances entreraient en conflit avec ceux du cœur.
Nouveau module (le dossier porte le nom technique du module) :
mkdir -p vemonmodule/tools/ve-module
cd vemonmodule
composer --working-dir=tools/ve-module require --dev velcome/prestashop-module-creator
tools/ve-module/vendor/bin/ve-module make:module
Module existant, depuis sa racine :
mkdir -p tools/ve-module
composer --working-dir=tools/ve-module require --dev velcome/prestashop-module-creator
tools/ve-module/vendor/bin/ve-module make:dev-tools
make:module et make:dev-tools ajoutent au composer.json du module les scripts de l'outil : après un clone, composer ve-module:install l'installe, puis composer ve-module -- <commande> le lance. Versionnez tools/ve-module/composer.lock : toute l'équipe et la CI utilisent ainsi la même version du package.
Premiers pas
Créer un module en interactif (questions, plan des fichiers, confirmation) :
tools/ve-module/vendor/bin/ve-module make:module
Ou sans question :
tools/ve-module/vendor/bin/ve-module make:module -n --name=vemonmodule --display-name="Mon module" --description="Affiche un bandeau sur la page d'accueil." --objective="Mettre en avant une offre sur la page d'accueil."
Ajouter ensuite un élément, par exemple le journal PSR-3, en relisant d'abord le plan avec --dry-run :
composer ve-module -- make:logger -n --dry-run
composer ve-module -- make:logger -n
Commandes
| Commande | Rôle |
|---|---|
make:module | crée le squelette d'un module, en interactif, par options ou depuis un fichier YAML (--config) |
make:dev-tools | installe l'outil dans un module existant, isolé dans tools/ve-module/ |
make:agents | ajoute les agents Claude (CLAUDE.md, .claude/agents/, docs/) |
make:logger | ajoute le journal PSR-3 (src/Logger/ModuleLogger.php, getLogger()) |
make:config-page | ajoute une page de configuration à onglets (getContent()) |
make:model | ajoute une classe ObjectModel et sa table |
make:controller | ajoute un contrôleur : page front, tâche planifiée, page du back-office ou Symfony |
make:route | ajoute une URL simplifiée à un contrôleur front |
make:tab | ajoute un onglet du back-office ($this->tabs) |
make:template | ajoute un gabarit front, back-office ou de hook |
make:service | ajoute un service déclaré dans config/ |
make:command | ajoute une commande console Symfony (bin/console) |
make:assets | ajoute la compilation des assets (webpack 5, sass, Babel) |
make:tests | ajoute des tests PHPUnit, PHPUnit étant isolé dans tools/phpunit/ |
make:upgrade | ajoute un script de mise à jour et relève la version du module |
make:zip | construit l'archive d'installation du module (dist/<nom>.zip), avec un vendor/ sans dépendances de développement |
make:audit | audite le module avant livraison, sans rien modifier (rapport texte ou JSON) |
Toutes, sauf make:audit (lecture seule), acceptent --dry-run et --force, et toutes, sauf make:module, --module-dir. Chacune termine par ses étapes suivantes (composer dump-autoload, vidage du cache…). Pour le détail : tools/ve-module/vendor/bin/ve-module list et tools/ve-module/vendor/bin/ve-module help <commande>.
Bon à savoir
- Module déjà installé : PrestaShop ne rejoue pas
install(). Pour un hook, un onglet ou une table ajoutés ensuite, réinitialisez le module (ses données sont supprimées) ou créez un script avecmake:upgrade: les étapes suivantes donnent la commande exacte. - Libellés d'onglet : PrestaShop retraduit les onglets avec le catalogue
Admin.Navigation.Menudu cœur ; un libellé identique à l'une de ses entrées (« Modules ») peut être remplacé. Donnez avecmake:tab --labelun libellé propre au module. - Archive d'installation :
make:zipproduitdist/<nom>.zip, à téléverser dans le back-office de la boutique ; levendor/y est reconstruit par Composer sans les dépendances de développement si le module a uncomposer.json, sinon archivé tel quel, avec un avertissement. Prérequis : l'extension PHP zip. Aucun appel à git : les fichiers non commités sont archivés tels quels. - Audit avant livraison :
make:auditvérifie le module en lecture seule : syntaxe PHP, fichiersindex.php, en-têtes de licence, fichiers de développement livrés, cohérence des versions et des hooks, fonctions interdites, garde_PS_VERSION_et droits trop ouverts des fichiers et dossiers livrés, modifiables par le groupe ou par les autres utilisateurs (identifiants et détail dansmake:audit --help) ; le contrôle de la garde écarte toujourssrc/et les dossiers déclarés dansautoload.psr-4ducomposer.jsondu module (classes PSR-4). Chaque constat est une erreur (module à ne pas livrer en l'état) ou un avertissement (point à vérifier) ; code de sortie 0, ou 1 en cas d'erreur, ou d'avertissement avec--strict, ou 2 si l'audit n'a pas pu commencer (module introuvable, option invalide, fichier refusé par le relevé ; message sur la sortie d'erreur).--format=jsonproduit un rapport JSON.make:ziplance le même audit avant Composer,--dry-runcompris : les erreurs bloquent l'archive, sauf si vous confirmez en mode interactif (question, non par défaut) ; avec-n, elles la bloquent toujours ; les avertissements non ;--no-auditsaute l'audit. Dans un script ou en CI, passez-n: sans lui (ni-q), la question est posée même sans terminal ; une entrée vide ou fermée vaut refus, mais une réponseoenvoyée par un tube construit l'archive. - Journaux : un fichier par jour dans
var/logs/, sans rotation ni purge ; prévoyez leur nettoyage. - Nginx ignore les
.htaccess: la règle à ajouter au serveur est donnée dans leCLAUDE.mddu module généré.
Les agents du module, générés par défaut par make:module (sauf --no-agents) ou par make:agents dans .claude/agents/, interviennent dans l'ordre du tableau : le chef-de-projet planifie, puis chaque sous-lot de docs/ROADMAP.md est réalisé par un seul agent, le developpeur ou l'integrateur-front selon l'agent indiqué dans la feuille de route, avant d'être relu par le code-reviewer, puis par securite :
| Agent | Rôle | Moment dans le workflow | Ce qu'il écrit |
|---|---|---|---|
chef-de-projet | consigne les demandes, les découpe en lots et sous-lots, désigne le prochain sous-lot et l'agent qui le réalise ; ne développe pas | à chaque nouvelle demande (au premier lancement, pour planifier le brief) ; après les deux APPROUVÉ, passe le sous-lot en « Terminé » ; bilan à l'utilisateur en fin de lot | docs/DEMANDES.md, docs/ROADMAP.md |
developpeur | réalise un seul sous-lot hors front (PHP, configuration, SQL), avec ses tests PHPUnit, en utilisant d'abord les commandes ve-module make:* | sous-lot désigné par le chef de projet, ou correction des points du code-reviewer ou de securite | le code et les tests du module, hors sous-lots front ; statut « En cours » puis « À relire » dans docs/ROADMAP.md |
integrateur-front | réalise un seul sous-lot front (gabarits Smarty et Twig, styles et scripts de views/), en utilisant d'abord make:template et make:assets | sous-lot front désigné par le chef de projet, ou correction des points du code-reviewer ou de securite | views/ et ses assets ; hors de views/, seulement ce qu'écrivent make:assets (classe principale, .gitignore) et make:template --type=hook (classe principale) ; statut « En cours » puis « À relire » dans docs/ROADMAP.md |
code-reviewer | relit le diff du sous-lot | après chaque sous-lot passé « À relire » | son verdict APPROUVÉ / À CORRIGER dans docs/REVIEWS.md ; lecture seule du code et des tests |
securite | contrôle le typage, les injections SQL, les droits des dossiers et fichiers et les critères de sécurité PrestaShop | après le verdict APPROUVÉ du code-reviewer, avant le commit du sous-lot | son verdict APPROUVÉ / À CORRIGER dans docs/SECURITE.md ; lecture seule du code et des tests |
- Intégration front : l'agent
integrateur-fronts'appuie sur le skill Claude Code/impeccable, recommandé, non obligatoire (impeccable.style), qui s'installe dans Claude Code par/plugin marketplace add pbakaus/impeccable, puis/plugin› Discover › Impeccable. Pour un module existant, lancezmake:agents --dry-run, puismake:agents --forcepour ajouter l'agent (voir « Mise à jour »). - Sécurité : l'agent
securitecontrôle notamment des critères de sécurité propres à PrestaShop (entrées, échappement des sorties, jetons des contrôleurs, upload, multiboutique…) ; un sous-lot n'est terminé qu'après son APPROUVÉ dansdocs/SECURITE.md. Pour un module existant, lancezmake:agents --dry-run, puismake:agents --force(voir « Mise à jour »).
Mise à jour
Les commandes ci-dessous supposent l'outil installé dans le module. Pour un module créé avec --no-dev-tools, ou dont le composer.json ne déclare pas les scripts ve-module*, suivez d'abord la section « Installation » pour un module existant : make:dev-tools les ajoute à son composer.json.
Le package se met à jour dans chaque module, depuis sa racine. Lisez d'abord le CHANGELOG des versions qui vous séparent de la dernière.
composer ve-module:update
Ce script lance composer --working-dir=tools/ve-module update velcome/prestashop-module-creator : il respecte la contrainte de tools/ve-module/composer.json (^<majeure>.<mineure>, par exemple ^1.0) et reste donc dans la version majeure installée. Si Composer refuse parce qu'une dépendance du package doit être mise à jour en même temps, transmettez-lui l'option après -- : composer ve-module:update -- --with-all-dependencies.
Version installée :
tools/ve-module/vendor/bin/ve-module --version
Le détail du paquet installé est donné par composer --working-dir=tools/ve-module show velcome/prestashop-module-creator.
Commitez ensuite tools/ve-module/composer.lock : les autres postes et la CI lancent composer ve-module:install après l'avoir récupéré, et utilisent ainsi la même version.
Version majeure : la contrainte empêche composer ve-module:update de la franchir, car une version majeure peut contenir des changements incompatibles, décrits dans le CHANGELOG. Relevez la contrainte, par exemple pour la version 2, puis commitez tools/ve-module/composer.json et tools/ve-module/composer.lock :
composer --working-dir=tools/ve-module require --dev velcome/prestashop-module-creator:^2.0
Fichiers du module : une mise à jour ne modifie que tools/ve-module/, aucun fichier du module. Les nouvelles commandes, par exemple make:zip, sont aussitôt disponibles, mais la liste des commandes du CLAUDE.md du module date du dernier make:agents, comme ses agents : un agent ajouté par une nouvelle version, par exemple integrateur-front ou securite (avec docs/SECURITE.md), n'y figure pas encore. Pour les rafraîchir, relancez-le, d'abord en simulation (--dry-run liste les fichiers en conflit) :
composer ve-module -- make:agents -n --dry-run
composer ve-module -- make:agents -n --force
make:agents --dry-run se termine en échec (code 1) tant qu'il signale des conflits : c'est attendu avant --force. Lancé par composer ve-module -- …, Composer affiche en plus « returned with error code 1 », ce qui n'est pas une panne.
--force remplace CLAUDE.md et .claude/agents/*.md : les modifications faites à la main et le « Contexte du projet » sont perdus, sauf si le brief est redonné par --config=<fichier.yaml> (fichier de module dont seule la section brief est lue) ou ressaisi : sans -n, make:agents repose en interactif les questions du brief, après confirmation. Les fichiers docs/*.md (demandes, feuille de route, relectures, contrôles de sécurité) sont conservés, même avec --force. Dès que CLAUDE.md ou un agent diffère de la version courante (agents d'une version antérieure, modifications à la main), sans --force, make:agents échoue sans rien écrire : aucun nouvel agent n'est ajouté tant que --force n'est pas passé. Les autres fichiers (docs/*.md, les .htaccess, un .gitattributes existant, complété des seules lignes manquantes) peuvent différer sans conflit ; PRODUCT.md et DESIGN.md ne sont pas touchés par make:agents (seul le .htaccess racine en refuse l'accès, et les lignes /PRODUCT.md export-ignore et /DESIGN.md export-ignore qu'il pose dans le .gitattributes les écartent de l'archive). Relisez le diff git avant de commiter.
Journal des modifications
Les évolutions de chaque version sont consignées dans le CHANGELOG.
Contribuer
Installation du poste, conventions, intégration continue et publication d'une version : voir CONTRIBUTING.
Licence
MIT, voir LICENSE. Auteur : Velcome E-commerce.