Structure des dossiers d’un module PrestaShop : guide pratique pour développeurs
Dernière révision en juin 2026, vérifié avec la documentation officielle PrestaShop 9 sur la structure des fichiers de module et testé sur des structures de modules PrestaShop 1.7, 8 et 9.
Un module PrestaShop ne se résume pas à un fichier PHP avec quelques hooks. Un module sérieux contient des contrôleurs, des templates, des assets, des traductions, des scripts de mise à jour, des dépendances Composer et parfois des définitions de services. Quand la structure des dossiers est claire, le module devient plus simple à déboguer, à mettre à jour et à maintenir.
La documentation officielle de PrestaShop propose un guide utile sur la structure des fichiers d’un module. Cet article en est la version pratique : à quoi sert chaque dossier, ce qui se passe souvent mal, et ce que je vérifie lorsque je relis un module.
Le dossier racine du module
Un module se trouve dans /modules/<module_name>/. Le nom du dossier doit être en minuscules et facile à prévoir. Le fichier PHP principal doit porter le même nom : mymodule/mymodule.php. Ce fichier gère l’installation, les hooks, les points d’entrée de configuration et les métadonnées du module utilisées par PrestaShop.
Si le fichier principal finit par compter des milliers de lignes, c’est généralement le signe que la logique métier devrait vivre ailleurs. Gardez la classe du module responsable du câblage, et déplacez la vraie logique dans des classes sous src/.
controllers/
Le dossier controllers contient les contrôleurs front et admin de style legacy. Les contrôleurs front se trouvent généralement dans controllers/front et servent à créer des pages publiques du module, des points d’entrée AJAX ou des actions côté client. Les contrôleurs admin vivent dans controllers/admin et alimentent les écrans du back office.
L’erreur fréquente consiste à mélanger le code du contrôleur avec les règles métier. Un contrôleur doit lire la requête, appeler des services ou des modèles, assigner les variables de template et renvoyer une réponse. Il ne doit pas contenir toutes les requêtes ni toutes les règles de rendu.
views/
Le dossier views contient les assets et les templates. Un module propre sépare views/templates/front, views/templates/admin et views/templates/hook. Le CSS, le JavaScript et les images doivent être rangés dans leurs propres dossiers d’assets.
C’est important parce que PrestaShop rend le même module dans des contextes très différents : un hook de page produit, une page de compte client, un écran de configuration du back office ou un contrôleur front autonome. Des emplacements de templates prévisibles facilitent largement les surcharges de thème et le débogage.
src/
Le dossier src est l’endroit où doivent vivre les classes modernes du module : services, entités, constructeurs de requêtes, validateurs, helpers de formulaire et clients d’intégration. Si une classe est réutilisable et testable, elle a probablement sa place ici plutôt que dans le fichier principal du module.
Pour les modules PrestaShop 8 et 9 plus importants, src est aussi l’endroit où peuvent apparaître des contrôleurs et des services de style Symfony. Même dans un module compatible avec l’ancien système, utiliser src pour la vraie logique rend la base de code plus facile à comprendre.
translations/
Les traductions ne sont pas un simple détail esthétique. Un module vendu dans toute l’Europe a besoin d’un wording fiable dans chaque langue prise en charge. Le dossier translations et les domaines de traduction modernes doivent être traités comme une partie du produit, pas comme une réflexion de dernière minute.
Lorsque je relis un module, je vérifie si les libellés, les messages d’erreur, les e-mails, les textes d’aide admin et les chaînes du front office disposent tous d’un chemin de traduction. Un mélange d’anglais codé en dur est l’un des moyens les plus rapides de donner à un module une impression d’inachevé.
upgrade/
Un vrai script de mise à jour doit effectuer une modification d’état concrète une seule fois, puis renvoyer un booléen auquel PrestaShop peut se fier :
<?php
if (!defined('_PS_VERSION_')) {
exit;
}
function upgrade_module_1_2_0($module)
{
return Db::getInstance()->execute(
'ALTER TABLE `' . _DB_PREFIX_ . 'mymodule_rule`
ADD `priority` INT UNSIGNED NOT NULL DEFAULT 0'
) && $module->registerHook('actionFrontControllerSetMedia');
}Le dossier upgrade contient les scripts de mise à jour versionnés. C’est là que les boutiques existantes reçoivent les nouvelles colonnes de base de données, les hooks, les onglets, les valeurs de configuration et les données migrées. Si un module a besoin d’une table ou d’une valeur de configuration, elle doit être créée à l’installation et lors de la mise à jour, pas vérifiée à chaque requête avec un helper ensureX() exécuté à l’exécution.
Les bons scripts de mise à jour sont sans surprise. Ils sont petits, idempotents quand c’est possible, et faciles à inspecter. C’est précisément cette simplicité qui rend les mises à jour client sûres.
vendor/
Le dossier vendor contient les dépendances Composer. Il ne doit pas devenir un endroit où l’on modifie manuellement du code tiers ou du code issu de packages partagés. Si un bug se trouve dans un package partagé, corrigez la source du package et synchronisez-la correctement. Modifier une copie placée dans vendor garantit seulement que le correctif disparaîtra plus tard.
config.xml et logo.png
config.xml est une description mise en cache du module, utilisée par PrestaShop dans les listes de modules et les mises à jour. Elle doit correspondre à la version du module. logo.png est l’icône du module affichée dans le back office. Ces fichiers semblent secondaires, mais des métadonnées obsolètes créent de la confusion lors du support et des mises à jour.
override/
PrestaShop prend en charge les overrides, mais ils doivent rester une solution de dernier recours. Les overrides sont puissants parce qu’ils modifient le comportement du cœur. Ils sont risqués exactement pour la même raison. La majeure partie du comportement d’un module doit être obtenue avec des hooks, des services, des contrôleurs et des templates.
Règle finale
Une bonne structure de dossiers ne rend pas un module bon à elle seule. Mais une mauvaise structure de dossiers rend chaque futur bug plus difficile. Si un module est facile à inspecter, il est plus facile à maintenir, plus facile à traduire, plus facile à mettre à jour et plus facile à rendre compatible avec PrestaShop 9.
Un squelette de module pratique
Un module propre n’a pas besoin d’être compliqué, mais il doit être prévisible. Une structure moderne typique ressemble à ceci :
modules/
mymodule/
mymodule.php
config.xml
composer.json
controllers/
front/
admin/
src/
Service/
Repository/
Form/
Installer/
views/
templates/
front/
admin/
hook/
css/
js/
img/
translations/
upgrade/
vendor/
Les dossiers exacts dépendent du module. Un tout petit module limité à un hook n’a pas forcément besoin d’une grande arborescence src/. Un module de paiement, de tunnel de commande ou de SEO en aura presque certainement besoin. L’objectif n’est pas de créer des dossiers vides. L’objectif est de rendre les responsabilités évidentes.
Ce qui doit rester dans le fichier principal du module
Le fichier PHP principal doit décrire le module et le connecter à PrestaShop. C’est le bon endroit pour les métadonnées, les points d’entrée d’installation et de désinstallation, l’enregistrement des hooks et des méthodes de hook légères. Ce n’est pas le bon endroit pour des milliers de lignes de logique métier, du SQL brut éparpillé dans les templates ou un rendu de formulaire complexe.
Quand le fichier principal devient un fourre-tout, chaque futur bug se complique. Le développeur doit comprendre la logique d’installation, l’interface admin, le rendu front et les changements de base de données dans un seul fichier. Déplacer la vraie logique dans des services n’est pas une mode architecturale ; c’est un outil de maintenance.
controllers/ doit rester léger
Les contrôleurs front et admin doivent coordonner le travail, pas tout porter eux-mêmes. Un contrôleur peut valider une requête, appeler un service, assigner des variables et renvoyer une réponse. Il ne doit pas contenir tout le moteur de tarification, tout le générateur de sitemap ou une longue routine de migration.
Cette séparation compte dans PrestaShop, car la même logique doit souvent être exécutée depuis différents endroits : un contrôleur front, un endpoint AJAX, une tâche cron, un script de mise à jour ou un hook. Si la logique est enfermée dans un seul contrôleur, la réutilisation devient du copier-coller.
src/ est l’endroit où le module devient maintenable
Le dossier src/ est l’endroit où doit vivre le code réutilisable : installateurs, repositories, validateurs, clients API, DTO, services, exportateurs, importateurs et classes utilitaires. Dans un contexte PrestaShop 8 ou 9, c’est aussi là qu’une organisation des services à la manière de Symfony devient plus simple.
Une règle utile : si une classe peut être testée ou comprise sans rendre un template Smarty, elle a probablement sa place dans src/. Cela facilite le débogage et aide les outils de codage par IA à comprendre le module sans devoir lire un énorme fichier procédural.
views/ n’est pas un dossier de logique
Les templates doivent afficher des données. Ils peuvent contenir des conditions clairement liées à la présentation, mais ils ne doivent pas interroger la base de données ni calculer des règles métier. Garder views/templates/front, views/templates/admin et views/templates/hook séparés permet de mieux comprendre où chaque template est utilisé.
Les assets doivent eux aussi être traçables. Si un module embarque du SCSS ou du JavaScript source, les fichiers compilés doivent avoir un chemin de build clair. Si une boutique signale un problème côté front, le développeur doit pouvoir dire quel fichier source a produit le CSS ou le JS utilisé à l’exécution.
upgrade/ fait partie du contrat
Beaucoup de bugs de modules viennent de l’idée que l’installation serait le seul cycle de vie. Les vrais modules évoluent. Ils ajoutent des colonnes de base de données, enregistrent de nouveaux hooks, créent des onglets, changent des noms de configuration et migrent d’anciennes données. Tout cela appartient aux scripts de mise à jour.
Un bon script de mise à jour est suffisamment idempotent pour survivre à des déploiements partiels, mais pas si vague que chaque requête essaie d’auto-réparer tout le module indéfiniment. L’installation et la mise à jour doivent créer l’état attendu. Le runtime doit l’utiliser.
vendor/ demande de la discipline
Les dépendances Composer facilitent la construction des modules, mais elles créent aussi un risque : il arrive que des développeurs patchent directement des fichiers vendor copiés. Cela peut corriger une boutique pendant une journée, mais ce n’est pas une correction maintenable. Si un package partagé contient un bug, corrigez la source du package, propagez-la correctement et assurez-vous que les modules consommateurs reçoivent la version mise à jour.
Ce qu’il ne faut pas mettre dans override/
Les overrides PrestaShop peuvent être puissants, mais ils font aussi partie des moyens les plus simples de rendre les mises à jour douloureuses. Un module qui modifie le comportement du cœur via des overrides doit avoir une raison très solide et une documentation claire. Dans beaucoup de cas, les hooks, la décoration de services, les routes de contrôleur, les événements Symfony ou la logique propre au module sont plus sûrs.
Comment ce guide s’articule avec les autres guides sur les dossiers
Cet article se concentre sur un module. Pour la structure plus large de la plateforme, consultez le guide de la structure des dossiers PrestaShop. Pour les thèmes, les templates, les assets et les thèmes enfants, consultez le tour d’horizon détaillé du dossier /themes/. Ensemble, ces trois guides couvrent les dossiers du cœur, les dossiers de thème et les dossiers de module.
Checklist finale
- Le fichier principal du module est lisible et n’est pas surchargé.
- Les contrôleurs appellent des services au lieu de porter toute la logique métier.
- Les templates affichent des données et évitent le travail en base de données.
- Les assets ont un chemin clair entre les sources et les fichiers exécutés au runtime.
- Les scripts d’installation et de mise à jour créent les onglets, les hooks, la configuration et les changements de schéma.
- Les traductions sont complètes pour chaque chaîne publique et admin.
- Les corrections vendor se font à la source, pas en modifiant des fichiers copiés.
- Les overrides sont évités sauf s’il n’existe aucune option native PrestaShop plus sûre.
Le dossier classé dans cet article est le dossier du module : /modules/<module_name>/. Il complète l’ensemble avec les guides existants sur le dossier du cœur et le dossier de thème.
Questions fréquentes
Dois-je utiliser le dossier src/, ou tout peut-il aller dans le fichier principal du module ?
PrestaShop n’impose pas de dossier src/ -- un module peut s’installer et fonctionner avec tout son code dans mymodule.php. Ce dossier est une convention de maintenabilité, pas une obligation. Pour un tout petit module limité à un hook, le fichier principal plus un template suffit. Dès que vous avez une vraie logique (requêtes, validateurs, clients API, importateurs), déplacez-la dans src/ avec un autoloading PSR-4 via composer.json. Cela garde le fichier principal lisible et rend les classes réutilisables depuis un contrôleur, une tâche cron ou un script de mise à jour sans copier-coller.
Quelle est la différence entre un override de module dans override/ et une surcharge de template de thème ?
Ils ne modifient pas la même chose. Le dossier override/ d’un module change le comportement PHP du cœur -- il remplace des méthodes de classes cœur comme Product ou ProductController dans toute la boutique. Une surcharge de template de thème change la façon dont un module s’affiche en plaçant une copie du fichier .tpl du module sous themes/your-theme/modules/<module>/. Les overrides PHP sont les plus risqués des deux, car un seul module peut surcharger une méthode cœur donnée à la fois, et les conflits apparaissent sous forme d’échecs d’installation. Privilégiez les hooks, la décoration de services ou des contrôleurs propres au module avant d’utiliser override/.
Faut-il committer et livrer vendor/ dans le ZIP du module ?
Oui, si le fichier principal du module fait require vendor/autoload.php. PrestaShop n’exécute pas composer install lorsqu’un marchand téléverse un ZIP, les dépendances doivent donc déjà être présentes, sinon le module provoquera une erreur fatale à l’installation avec une classe manquante. Livrez un vendor/ construit avec composer install --no-dev. Ce qu’il ne faut absolument pas faire, c’est modifier à la main les fichiers dans vendor/ -- ces modifications seront écrasées à la prochaine mise à jour des dépendances. Corrigez plutôt la dépendance à sa source.
Pourquoi mon module affiche-t-il le mauvais numéro de version dans le back office après l’avoir augmenté ?
PrestaShop lit les métadonnées du module à deux endroits qui doivent être cohérents : la propriété $this->version dans le fichier PHP principal et la balise <version> dans config.xml. config.xml est un descripteur mis en cache utilisé dans les listes de modules ; si vous augmentez la version PHP mais laissez config.xml obsolète, la liste et la logique de mise à jour ne sont plus d’accord, et les mises à jour peuvent mal se déclencher. Gardez les deux valeurs identiques à chaque version publiée.
Où les contrôleurs front deviennent-ils réellement des URL ?
Un fichier placé dans controllers/front/display.php, avec une classe nommée MyModuleDisplayModuleFrontController, est accessible via le générateur de liens de PrestaShop, typiquement sous la forme index.php?fc=module&module=mymodule&controller=display (et sous forme d’URL simplifiée une fois les URL simplifiées activées). Les contrôleurs admin dans controllers/admin/ ont besoin d’un onglet enregistré (créé dans install() ou dans un script de mise à jour) avant d’apparaître et de devenir routables dans le back office. Mettre le fichier dans le bon dossier est nécessaire, mais pas suffisant -- le nom de la classe du contrôleur et, pour l’admin, l’enregistrement de l’onglet sont ce qui le rend réellement actif.
Si vous maintenez plusieurs modules, le même squelette répété entre eux est ce qui rend un catalogue maintenable. Pour la vue globale de la plateforme et de la place des modules par rapport au cœur, lisez le guide de la structure des dossiers PrestaShop ; pour la partie thème des surcharges et des templates, consultez le tour d’horizon détaillé du dossier /themes/. Quand le rôle d’un module est une tâche planifiée qui vit en partie dans controllers/ et en partie dans un point d’entrée CLI, les modèles présentés dans notre guide des tâches cron montrent comment ces éléments s’articulent.
Articles connexes
Commentaires
Laisser un commentaire
Partagez une question, un détail de pose ou un retour qui pourrait aider un autre lecteur.