Adapter ses modules pour PrestaShop 9 : guide rapide

Adapter ses modules à PrestaShop 9 n’est plus une option sympathique à mettre « pour plus tard » : c’est devenu une condition de survie sur le marketplace officiel. Depuis le lancement de PrestaShop 9.0.0 en juin 2025 et le durcissement des règles de validation en 2026, les développeurs doivent anticiper à la fois les contraintes techniques (PHP 8.1+ / 8.4, nouvelle API, thème Hummingbird) et les exigences du marketplace (compatibilité déclarée, nom technique unique, zéro notice en debug).

Ce guide rapide propose un plan d’action pragmatique pour faire évoluer un module existant (1.6/1.7/8) vers PrestaShop 9 sans repartir de zéro. L’objectif n’est pas de couvrir tous les cas exotiques, mais de vous donner un chemin clair : quoi vérifier en priorité, quelles règles du marketplace respecter absolument, comment tester et sécuriser votre module pour les futures versions 9.x.

1. Comprendre les nouvelles règles du marketplace PrestaShop 9

Depuis le 1er février 2026, le PrestaShop Marketplace applique une règle stricte : toute mise à jour de module soumise doit être compatible avec la dernière version majeure disponible, actuellement PrestaShop 9.x. Si votre ZIP ne déclare pas explicitement cette compatibilité, la validation est automatiquement rejetée, même si le module fonctionne techniquement. Cette exigence vaut également pour tout nouveau produit, qui doit annoncer un support explicite de la série 9.x.

La compatibilité n’est plus une simple mention marketing dans la description : elle devient une méta‑donnée contrôlée par la plateforme. Les versions de PrestaShop supportées (par exemple « 1.7.8 , 9.0.x ») sont lues et vérifiées lors du processus de revue. Si la branche 9 n’est pas listée, votre module est bloqué avant même la phase de tests fonctionnels. D’un point de vue business, ignorer cette règle signifie se couper des boutiques qui migrent vers PrestaShop 9 en 2025, 2026.

En parallèle, les standards techniques 2025, 2026, détaillés dans les Technical Development Standards, renforcent d’autres obligations : structure minimale du module, sécurité, interdiction de modifier le core, et surtout absence de notices en mode debug. Avant de toucher une seule ligne de code, il est donc indispensable de lire ou relire la documentation officielle du marketplace afin de savoir quels points sont bloquants et lesquels sont seulement recommandés.

2. Préparer son module à la stack technique de PrestaShop 9

PrestaShop 9 élève le niveau technique de base : la plateforme nécessite au minimum PHP 8.1 et recommande PHP 8.4, tout en supportant MySQL ≥ 5.7 ou MariaDB ≥ 10.2. Pour un module ancien, conçu avec PHP 5.6 ou 7.x en tête, cette évolution implique un audit complet du code. Les changements de comportement (types plus stricts, gestion des erreurs, dépréciations) peuvent générer des warnings ou casser silencieusement certaines fonctionnalités si vous ne les anticipez pas.

Commencez par exécuter votre module sur un environnement PrestaShop 9 avec PHP 8.4 et le mode debug activé. Surveillez les notices liées à la signature des méthodes (types scalaires, retours stricts), à l’utilisation de fonctions dépréciées ou à des librairies externes qui ne seraient plus compatibles. Vérifiez également les extensions requises (cURL, intl, mbstring, etc.) : si votre module les utilise, assurez‑vous qu’elles sont disponibles et compatibles avec les prérequis système de PrestaShop 9.

Côté base de données, adaptez vos requêtes pour respecter les bonnes pratiques actuelles : utilisez les méthodes de la couche DB de PrestaShop, évitez les SQL non préparés et tenez compte des modes plus stricts de MySQL/MariaDB (STRICT_TRANS_TABLES, NO_ZERO_DATE…). L’objectif est double : garantir le bon fonctionnement immédiat sur la stack 9.x et réduire les risques lors des futures mises à jour mineures (9.1, 9.2…) où les exigences PHP et DB pourraient encore se durcir.

3. Respecter la structure minimale et le nom technique unique

Depuis décembre 2025, une contrainte majeure change la façon d’aborder la compatibilité multi‑versions : le nom technique d’un module (nom du dossier dans /modules et nom du fichier principal PHP) doit rester strictement identique pour toutes les versions ZIP de ce module. Autrement dit, vous ne pouvez plus publier une variante « mymodule9 » à côté d’un « mymodule » historique pour gérer la compatibilité. Toute la logique de support des différentes versions de PrestaShop doit vivre dans un seul et même module.

Concrètement, votre module doit respecter une structure minimale validée par la documentation officielle « Creating your first module » pour PrestaShop 9 et par le Validator. Cela signifie : un dossier /modules/mymodule (nom technique en minuscules alphanumériques), un fichier principal mymodule.php dans ce dossier, et l’inclusion systématique du garde‑fou de sécurité en début de fichier : if (!defined('_PS_VERSION_')) { exit; }. Cette structure est contrôlée automatiquement lors de la soumission au marketplace.

Si votre historique est complexe (plusieurs branches 1.6, 1.7, 8 avec des noms de dossier différents), la migration vers PrestaShop 9 est le moment d’unifier tout cela. Centralisez votre code dans un seul module, ajoutez si nécessaire une couche d’abstraction pour gérer les différences entre versions de PrestaShop, et mettez en place des scripts de mise à jour (upgrade.php) pour migrer proprement les données de configuration et de schéma sans casser les installations existantes.

4. Déclarer correctement la compatibilité et gérer les mises à jour

Les nouvelles règles du marketplace exigent une déclaration précise des versions de PrestaShop supportées par chaque module. Il ne suffit plus de mentionner « compatible PrestaShop 1.7+ » : vous devez indiquer les branches exactes, par exemple « 1.7.8.x , 9.0.x ». Cette information est utilisée automatiquement par la plateforme pour filtrer les modules affichés aux marchands et pour décider si une mise à jour peut être acceptée. À partir du 01/02/2026, l’absence explicite de la série 9.x dans cette métadonnée entraîne un rejet de la mise à jour.

En interne, cela vous oblige à adopter une sémantique de version claire (versioning sémantique type MAJEUR.MINOR.PATCH) et à synchroniser cette version avec les déclarations de compatibilité. Par exemple, un passage à PrestaShop 9 sans rupture majeure côté API module peut se traduire par une version 2.5.0 de votre module, avec une note de version indiquant l’ajout du support 9.0.x. Cette discipline facilite aussi l’intégration avec le Module Manager du back‑office, qui se base sur ces champs pour proposer ou non une mise à jour.

PrestaShop 9 propose en outre un mécanisme d’auto‑update pour les modules, documenté dans la section « Enabling the Auto‑Update ». En respectant les bonnes pratiques (déclaration des compatibilités, distribution via l’API dédiée, gestion propre des scripts d’upgrade), votre module pourra être mis à jour automatiquement sur les boutiques, y compris fraîchement migrées depuis des versions plus anciennes grâce à des outils comme « 1‑Click Migrate ». Cette continuité d’expérience est un argument commercial fort : les marchands veulent pouvoir migrer leur boutique et leurs modules sans friction.

5. Garantir le « zéro notice » en mode debug

Un des changements les plus visibles pour les développeurs est l’exigence « zéro notice » en mode debug. Les standards techniques imposent que les modules ne génèrent aucun message d’erreur, d’avertissement, ni même de simple notice PHP lorsque le mode debug est activé dans PrestaShop 9. En pratique, cela signifie que vous devez assainir tout le code : variables non définies, indices de tableau inexistants, signatures de méthodes incompatibles, dépréciations PHP 8.1+ / 8.4, hooks obsolètes, services Symfony mal typés, etc.

La démarche la plus efficace consiste à activer le mode debug sur une boutique de test PrestaShop 9, installer votre module, parcourir toutes les fonctionnalités (back‑office et front‑office) et relever systématiquement chaque message affiché. Combinez cela avec l’analyse des logs PHP et, idéalement, l’exécution de votre code sous un outil de qualité (PHPStan, Psalm) configuré pour PHP 8.1+. L’objectif est de corriger la source de chaque notice plutôt que de masquer les erreurs par des @ ou des conditions silencieuses.

Cette exigence n’est pas uniquement cosmétique : elle conditionne l’acceptation de votre module sur le marketplace et garantit sa robustesse sur la durée. Un module qui tourne proprement en mode debug sur PHP 8.4 a de fortes chances de rester compatible aux futures itérations de la branche 9.x. À l’inverse, un code truffé de notices peut masquer des bugs fonctionnels qui se révéleront en production, surtout lorsque les marchands activeront des niveaux de reporting d’erreurs plus stricts.

6. Adapter le front‑office au thème Hummingbird et à Bootstrap 5

PrestaShop 9 introduit un nouvel acteur majeur côté front‑office : le thème officiel Hummingbird, basé sur Bootstrap 5.2, aux côtés du thème classique héritée « classic » qui repose sur Bootstrap 4. De nombreux modules historiques ont été conçus uniquement pour le thème classic, en s’appuyant directement sur ses classes CSS (grilles, composants, helpers JS). Lorsqu’un marchand active Hummingbird, ces hypothèses ne tiennent plus forcément : grilles qui sautent, alignements cassés, scripts JS obsolètes.

Pour adapter un module à PrestaShop 9, il est donc incontournable de tester tous les hooks front importants (displayHeader, displayFooter, displayHome, displayLeftColumn, displayRightColumn, etc.) sur les deux thèmes officiels. Vérifiez le rendu visuel, la réactivité en mobile, la compatibilité avec les composants Bootstrap 5.2, et l’absence de conflit CSS/JS. Si votre module surcharge ou étend des templates .tpl du thème classic, envisagez de fournir des templates spécifiques à Hummingbird ou de basculer vers une approche plus indépendante du thème.

Une bonne pratique consiste à encapsuler votre style dans un namespace CSS propre (par exemple un conteneur .mymodule-widget) et à limiter au maximum la dépendance aux classes du thème. Lorsque vous devez tirer parti de la grille Bootstrap, veillez à adopter la syntaxe de Bootstrap 5.2 (classes, breakpoints, suppression de certains utilitaires) et à ne plus compter sur des composants retirés. Cette approche rend votre module bien plus résilient face aux changements de thème, y compris ceux de thèmes tiers basés sur Bootstrap 5.

7. Exploiter le Validator, le Module Generator et la nouvelle API

Pour accélérer l’adaptation de vos modules à PrestaShop 9, le PrestaShop Validator est un allié précieux. Cet outil en ligne permet d’uploader un ZIP de module (ou de pointer vers un dépôt GitHub) et de recevoir un rapport détaillé sur les erreurs, mauvaises pratiques et incompatibilités avec les standards techniques en vigueur. Avant même de soumettre votre module au marketplace, vous pouvez ainsi corriger la plupart des problèmes bloquants détectés automatiquement.

Le Validator inclut également un Module Generator, très utile pour les projets plus anciens (1.6/1.7) qui nécessitent une refonte structurelle. En générant un squelette de module conforme aux derniers standards (structure de dossiers, hooks typiques, gestion des mises à jour, services Symfony), vous disposez d’une base de référence pour refactorer votre ancien code. Il devient plus simple d’introduire progressivement les bonnes pratiques sans réécrire tout le module d’un bloc.

Enfin, l’adaptation à PrestaShop 9 est l’occasion de repenser vos intégrations externes grâce à la nouvelle API basée sur API Platform et le pattern CQRS, avec authentification OAuth2. Si votre module utilisait l’ancienne Webservice API XML/REST, vous pouvez commencer à migrer certaines fonctionnalités vers les nouveaux endpoints plus riches et mieux structurés. Les modules qui font office de passerelles vers des ERP, CRM ou PIM bénéficient ainsi de points d’entrée plus granulaires, tout en offrant aux marchands une intégration plus sécurisée et pérenne.

8. Sécurité, intégrité des données et compatibilité long terme

Les Technical Development Standards réaffirment des règles strictes sur la sécurité et l’intégrité de la base de données. Il est désormais clairement interdit de modifier les tables natives de PrestaShop (tables core) via des ALTER TABLE ou tout autre changement de schéma direct. De même, toute modification des fichiers du core ou d’autres modules est proscrite. Les overrides agressifs, les hacks dans le code source et les changements intrusifs dans la base sont autant de raisons de rejet sur le marketplace.

Adapter un module 1.6/1.7 à PrestaShop 9 signifie donc, en pratique, identifier et supprimer ces pratiques. Toute la logique métier doit être encapsulée dans votre module : via les hooks, les services Symfony ou, lorsque c’est réellement nécessaire, des overrides contrôlés et documentés. Pour stocker vos propres données, créez vos tables dédiées avec un préfixe propre au module, en suivant les conventions de nommage et sans toucher aux tables du core. Ce découplage est essentiel pour garantir la compatibilité avec les futures releases 9.x.

Cette approche peut demander un effort initial important, surtout si votre module est ancien et très intrusif, mais elle apporte un bénéfice majeur : une maintenance simplifiée et des mises à jour de PrestaShop beaucoup moins risquées pour les marchands. À l’heure où les boutiques migrent massivement vers PrestaShop 9 à l’aide d’outils comme « 1‑Click Migrate », les modules qui respectent ces contraintes sont ceux qui inspirent confiance et qui restent installés sur le long terme.

Adapter ses modules à PrestaShop 9 n’est pas un simple exercice cosmétique : c’est un chantier qui touche à la fois la qualité du code, la structure du module, le front‑office, la sécurité et les intégrations externes. En respectant les nouvelles règles du marketplace (compatibilité obligatoire 9.x, nom technique unique, déclaration fine des versions supportées), en visant le « zéro notice » en mode debug et en testant soigneusement Hummingbird comme classic, vous placez votre module au niveau attendu pour la génération 9.x.

La bonne nouvelle est que l’écosystème fournit désormais des outils et une documentation centralisée pour vous accompagner : DevDocs 9 pour les modules, thèmes et API, Validator et Module Generator pour normaliser la structure, et une nouvelle API moderne prête pour les intégrations sérieuses. En vous appuyant sur ces ressources et en planifiant une refonte progressive plutôt qu’un simple patch, vous transformerez l’obligation de compatibilité PrestaShop 9 en véritable opportunité : offrir aux marchands des modules plus robustes, mieux intégrés et plus faciles à maintenir dans les années à venir.