Module PrestaShop qui ne fonctionne plus après une mise à jour

Quatre familles de causes, pas une

Un module PrestaShop ne fonctionne plus après une mise à jour, et le symptôme varie : un bloc a disparu du front, une page d'administration renvoie une erreur, ou le site entier tombe. Derrière ces symptômes, on retrouve presque toujours l'une de ces quatre causes : un hook perdu, un override en conflit, une dépendance retirée du cœur, ou un cache resté incohérent.

Identifier la bonne famille en premier fait gagner des heures.

Cause 1 : le hook n'est plus enregistré

Symptôme : le module est actif, sa configuration est intacte, mais son contenu n'apparaît plus.

Les noms de hooks ont évolué au fil des versions. Les anciens noms comme hookHeader sont devenus hookDisplayHeader, et certains points d'accroche ont disparu. Un module ancien continue de s'installer, mais ne s'affiche plus.

Vérifiez l'état réel en base :

SELECT h.name AS hook, m.name AS module, hm.position
FROM ps_hook_module hm
JOIN ps_hook h ON h.id_hook = hm.id_hook
JOIN ps_module m ON m.id_module = hm.id_module
WHERE m.name = 'nom_du_module';

Si le hook attendu est absent, réenregistrez-le depuis l'onglet Positions du back-office, ou en réinstallant le module — après avoir vérifié que sa désinstallation ne supprime pas ses données.

Regardez aussi ps_hook_module_exceptions : une exception ajoutée pour masquer un bloc sur une page précise finit parfois par le masquer partout.

Le cas inverse existe : un module qui se réenregistre tout seul sur un hook après chaque mise à jour, parce que sa méthode d'installation est rejouée. Il faut alors corriger le module, pas la base.

Cause 2 : un override en conflit

Symptôme : erreur fatale mentionnant une classe déjà déclarée, ou comportement incohérent d'une fonctionnalité du cœur.

PrestaShop n'autorise qu'un seul override par classe. Deux modules qui surchargent Cart ou Product entrent en collision, et le second gagne silencieusement.

Le fichier à connaître est var/cache/prod/class_index.php. Il contient la table de correspondance entre chaque classe et le fichier qui l'implémente. Tant qu'il n'est pas régénéré, un override ajouté ou retiré n'est pas pris en compte, ce qui produit des erreurs fatales incompréhensibles.

Le réflexe après toute modification dans override/ :

rm -f var/cache/prod/class_index.php
rm -rf var/cache/prod/*

Pour tester si un override est en cause, renommez temporairement le dossier override/ en override_off/ et rechargez. Si le site revient, vous avez isolé la famille de causes.

Cause 3 : une dépendance retirée du cœur

C'est la cause dominante depuis PrestaShop 9, et la plus brutale : erreur fatale immédiate sur une classe introuvable.

PrestaShop 9 a retiré plusieurs bibliothèques historiques :

• Swift Mailer remplacé par Symfony Mailer ;
• Guzzle remplacé par Symfony HTTP Client ;
• League Tactician remplacé par Symfony Messenger ;
• sensio/framework-extra-bundle supprimé, donc les annotations de route et de template ne fonctionnent plus.

Tout module qui déclare use GuzzleHttp\Client; ou use League\Tactician\...; produit une erreur fatale dès son chargement.

Repérez les modules concernés avant même de migrer :

grep -rl "GuzzleHttp\|League\\\\Tactician\|Swift_Mailer" modules/

Par ailleurs, FrameworkBundleAdminController est déprécié au profit de PrestaShopAdminController, et les contrôleurs d'administration doivent désormais être déclarés comme services avec injection de dépendances. Un module dont le contrôleur back-office renvoie une erreur 500 après passage en 9 relève presque toujours de ce point.

Enfin, l'authentification du back-office est entièrement portée sur Symfony : les modules de connexion unique ou de double authentification qui s'appuyaient sur le cookie historique cessent de fonctionner.

Cause 4 : un cache resté incohérent

Symptôme : comportement erratique, qui change d'une page à l'autre ou disparaît en navigation privée.

Après toute mise à jour, purgez dans cet ordre :

rm -rf var/cache/prod/* var/cache/dev/*

Puis, dans Paramètres avancés > Performances, désactivez temporairement les options de combinaison et de compression des fichiers, videz le cache Smarty, et rechargez. Ces options regroupent les fichiers JavaScript et cassent régulièrement les modules qui chargent leurs scripts de façon asynchrone.

Vérifiez aussi les permissions sur var/ : un cache qui ne peut pas être réécrit produit des symptômes aléatoires très difficiles à interpréter.

La méthode de remise en service

1. Activer le mode debug, en créant config/defines_custom.inc.php avec define('_PS_MODE_DEV_', true); plutôt qu'en modifiant le fichier du cœur. Votre réglage survivra ainsi à la prochaine mise à jour.
2. Lire les logs dans var/logs/ et dans le journal d'erreurs PHP de l'hébergeur. Le nom de la classe manquante ou du service introuvable désigne le module coupable.
3. Désactiver le module suspect en base, sans passer par le back-office qui peut être inaccessible :

UPDATE ps_module SET active = 0 WHERE name = 'nom_du_module';

4. Vider le cache, vérifier que le site revient, puis traiter proprement : mise à jour du module auprès de son éditeur, ou correction du code.
5. Désactiver le mode debug avant de rouvrir au public.

Éviter le prochain épisode

La règle qui économise le plus de temps : ne jamais mettre à jour directement en production. Une préproduction, une recette écrite couvrant le tunnel de commande, les paiements, les emails et les transporteurs, et un inventaire des modules à jour suffisent à transformer une panne en non-événement.

Pour les modules développés spécifiquement, nos règles de développement d'un module sur mesure détaillent ce qui rend un module résistant aux mises à jour.

Un module bloque votre boutique ?

Nous remettons en service les modules cassés et corrigeons le code quand l'éditeur ne suit plus. Voir le développement de modules PrestaShop.