Comment activer le mode debug sur PrestaShop ?

Une page blanche, une erreur 500, un module qui casse l’affichage : sur une boutique en ligne, ces incidents arrivent souvent au pire moment, sans le moindre indice sur leur origine. Le mode debug PrestaShop existe précisément pour transformer ces écrans muets en messages d’erreur exploitables.

Activé le temps d’un diagnostic, il révèle l’erreur PHP exacte, la requête SQL fautive ou le fichier en cause, puis se désactive une fois la correction faite. Cet article détaille à quoi sert ce mode, comment l’activer le mode debug PrestaShop selon votre version (1.6, 1.7, 8 ou 9), comment lire les erreurs qu’il affiche et comment le couper proprement avant de remettre la boutique en production.

À quoi sert le mode debug PrestaShop

Par défaut, une boutique en production masque les détails techniques des erreurs. Quand une exception PHP survient, le visiteur tombe sur une page blanche ou un laconique « Une erreur s’est produite », sans aucune information sur la cause.

Ce comportement protège le client et évite d’exposer la structure du site, mais il rend le diagnostic impossible côté administrateur.

Le mode debug PrestaShop inverse cette logique. Une fois activé, la constante interne _PS_MODE_DEV_ passe à true et le moteur affiche l’intégralité des avertissements PHP, le message d’exception, la pile d’appels (stack trace) et le chemin du fichier concerné.

Cette fonctionnalité s’adresse au gérant de la boutique, au développeur ou au support technique qui cherche à comprendre pourquoi un module, un thème ou une mise à jour provoque un dysfonctionnement.

Les situations typiques qui justifient son activation sont nombreuses sur un site e-commerce :

• Page blanche après l’installation ou la mise à jour d’un module
• Erreur 500 (Internal Server Error) sur le front-office ou le back-office
• Bug d’affichage lié au thème ou à une surcharge de template
• Problème de variation de produit, de traduction manquante ou de panier inaccessible
• Comportement anormal après une migration de serveur ou un changement de version PHP

Ce mode reste un outil de diagnostic ponctuel. Il n’a pas vocation à rester actif en permanence : son rôle s’arrête au moment où l’erreur est identifiée. La confier à un professionnel reste pertinent quand le diagnostic touche au cœur des fichiers, mais activer la fonction soi-même permet souvent de localiser le module ou le fichier fautif en quelques minutes.

Les deux méthodes pour activer le mode debug PrestaShop

Il existe deux façons d’activer le mode debug, et le choix dépend d’un seul critère : avez-vous encore accès au back-office de votre boutique ?

• Via le back-office, dans Paramètres avancés > Performances. C’est la méthode la plus rapide, recommandée tant que l’administration reste accessible.
• Via le fichier defines.inc.php, par FTP ou gestionnaire de fichiers de l’hébergeur. C’est la seule option quand une page blanche bloque aussi l’accès au back-office.

Les deux méthodes produisent le même résultat : elles font basculer la constante _PS_MODE_DEV_ sur true. La voie par fichier offre en plus une variante avancée, l’activation du mode debug PrestaShop par adresse IP, détaillée plus bas, qui réserve l’affichage des erreurs à votre seule connexion.

Avant toute intervention directe dans les fichiers, une sauvegarde du dossier config reste la précaution de base.

Activer le mode debug depuis le back-office en 1.7, 8 et 9

Depuis PrestaShop 1.7, et sur les versions 8 et 9 qui en reprennent l’interface, l’activation se fait sans toucher au code. Tout passe par un interrupteur dans le back-office, ce qui rend la manipulation accessible même sans compétence technique :

1. Connectez-vous au back-office de votre boutique
2. Ouvrez le menu Paramètres avancés > Performances
3. Repérez la section Mode debug en haut de page
4. Passez l’option Mode debug sur Oui
5. Cliquez sur Enregistrer

Le mode est immédiatement actif. Rechargez la page qui posait problème : à la place de l’écran blanc, le message d’erreur complet s’affiche désormais, avec le fichier et la ligne en cause. Une icône en forme d’insecte apparaît en haut du back-office et signale que le mode debug PrestaShop est enclenché, ce qui vous évite de l’oublier.

Sur les versions récentes, ce réglage agit sur la même constante que le fichier de configuration. Activer l’interrupteur dans Performances revient donc exactement à modifier _PS_MODE_DEV_ à la main, en plus simple. Cette méthode convient à la grande majorité des incidents sur une boutique PrestaShop, du module défaillant au bug de thème, dès lors que l’administration répond encore.

Modifier defines.inc.php quand le back-office est inaccessible

Quand une erreur fatale verrouille aussi l’accès à l’administration, l’interrupteur du back-office devient inutilisable. Il faut alors activer le débogage directement dans le fichier de configuration, par FTP ou via le gestionnaire de fichiers de votre hébergeur. Cette voie fonctionne sur toutes les versions, de la 1.6 jusqu’à la 9.

1. Connectez-vous à votre serveur avec un client FTP (FileZilla par exemple) ou le gestionnaire de fichiers de l’hébergeur
2. Ouvrez le dossier /config/ à la racine de la boutique
3. Éditez le fichier defines.inc.php
4. Repérez la ligne define('_PS_MODE_DEV_', false);
5. Remplacez false par true pour obtenir define('_PS_MODE_DEV_', true);
6. Enregistrez le fichier et renvoyez-le sur le serveur

Rechargez ensuite la page en erreur : le détail technique apparaît à l’écran. Sur les boutiques en 1.6, cette modification du fichier defines.inc.php était d’ailleurs l’unique moyen d’activer le débogage, l’interrupteur de back-office n’existant pas encore à cette époque.

La logique reste strictement identique en 8 et 9, seul l’environnement graphique a évolué autour.

Toute édition d’un fichier de configuration comporte un risque : une accolade ou un point-virgule oublié suffit à provoquer une nouvelle erreur. Conservez une copie du fichier original avant modification, et travaillez avec un éditeur de code qui respecte l’encodage UTF-8 sans BOM plutôt qu’un simple bloc-notes.

Limiter l’affichage des erreurs à votre adresse IP

Le défaut majeur du débogage classique est qu’il rend les messages d’erreur visibles par n’importe quel visiteur de la boutique. Sur un site en production qui reçoit du trafic, c’est à la fois mauvais pour l’image et risqué pour la sécurité, puisque ces messages dévoilent des chemins de fichiers et des éléments de structure interne.

La parade consiste à activer le mode debug uniquement pour votre propre adresse IP. Vous voyez alors les erreurs détaillées pendant que les clients continuent de naviguer normalement. Dans le fichier defines.inc.php, remplacez la ligne de définition simple par un test conditionnel sur l’IP du visiteur :

/* Debug only */
if (!defined('_PS_MODE_DEV_') && in_array($_SERVER['REMOTE_ADDR'], array('::1', 'localhost', '127.0.0.1', 'xx.xx.xx.xx'))) {
define('_PS_MODE_DEV_', true);
} else {
define('_PS_MODE_DEV_', false);
}

Remplacez xx.xx.xx.xx par votre adresse IP publique, que vous pouvez relever en cherchant « mon IP » sur un moteur de recherche. Seules les connexions provenant de cette adresse déclencheront le mode développeur ; pour tous les autres visiteurs, la boutique reste en mode production silencieux.

Cette approche par IP est la plus saine sur un site actif, car elle évite de basculer toute la boutique en mode développeur. Une alternative consiste à passer la boutique en mode maintenance le temps du diagnostic, ce qui ferme le front-office au public pendant l’intervention.

Lire et interpréter les erreurs affichées

Activer le débogage ne sert à rien si l’on ne sait pas lire ce qui s’affiche. Un message PrestaShop en mode développeur suit toujours une structure lisible, même pour un non-développeur. Il indique le type d’erreur, le message, le fichier concerné et la ligne exacte, suivis de la pile d’appels qui retrace l’enchaînement ayant mené au plantage.

Quelques types de messages reviennent fréquemment et orientent vite le diagnostic :

Type de message	Cause probable	Piste de résolution
Fatal error / Uncaught Exception	Module ou surcharge incompatible avec la version	Désactiver le module cité, vérifier la compatibilité de version
Notice / Warning	Variable non définie, fichier de langue manquant	Souvent sans gravité, à corriger dans le template ou la traduction
Class not found	Cache de classes obsolète après une mise à jour	Vider le dossier cache, régénérer l’autoload
Allowed memory size exhausted	Limite mémoire PHP trop basse	Augmenter memory_limit côté serveur ou hébergeur

Le réflexe le plus utile consiste à lire le chemin du fichier mentionné. S’il pointe vers /modules/nomdumodule/, le coupable est ce module précis ; s’il pointe vers /themes/, le problème vient du thème ou d’une surcharge. Cette seule information permet de cibler l’intervention au lieu de chercher au hasard.

Exploiter le profiling et les requêtes SQL

Au-delà de l’affichage des erreurs, le mode debug PrestaShop ouvre l’accès au profiling, un outil d’analyse de performance souvent méconnu. Là où le débogage simple traque les pannes, le profiling traque la lenteur : il mesure le temps de génération de chaque page, le nombre de requêtes SQL exécutées et leur durée.

Pour l’activer, ouvrez le fichier config/defines.inc.php et passez la constante _PS_DEBUG_PROFILING_ de false à true. Un bandeau apparaît alors en pied de chaque page du front-office, détaillant le temps de chargement, l’occupation mémoire et la liste des requêtes SQL les plus coûteuses.

Ces données sont précieuses quand une boutique devient lente sans raison apparente. Une requête SQL répétée des centaines de fois, un module qui interroge la base à chaque chargement ou une page produit anormalement lourde se repèrent immédiatement dans le profiling.

Ces signaux alimentent directement les chantiers d’optimisation, notamment dans une démarche de référencement d’une boutique PrestaShop, où la vitesse de chargement pèse sur le positionnement.

Le profiling reste, lui aussi, à désactiver dès l’analyse terminée, car il alourdit chaque page.

Désactiver le mode debug avant de repasser en production

L’étape la plus souvent négligée est aussi la plus importante. Une fois l’erreur identifiée et corrigée, le mode debug doit impérativement être coupé. Le laisser actif sur une boutique en production expose des informations techniques à tous les visiteurs, ralentit l’affichage et constitue une faille de sécurité réelle, puisque la structure interne du site devient lisible.

La désactivation suit le chemin inverse de l’activation, selon la méthode utilisée :

1. Depuis le back-office : retournez dans Paramètres avancés > Performances, repassez l’option Mode debug sur Non et enregistrez
2. Depuis le fichier : rouvrez config/defines.inc.php et remettez define('_PS_MODE_DEV_', false);
3. Si vous aviez activé le profiling, repassez également _PS_DEBUG_PROFILING_ sur false
4. Videz le cache de la boutique pour repartir sur un affichage propre

Vérifiez ensuite que la page corrigée s’affiche normalement et qu’aucun message technique ne subsiste sur le front-office. Une boutique remise en production doit présenter au visiteur une expérience parfaitement silencieuse, sans la moindre trace du diagnostic mené en coulisses.

Erreurs fréquentes et bonnes pratiques

Quelques pièges récurrents font perdre du temps lors de l’utilisation du mode debug PrestaShop. Les connaître évite de tourner en rond face à un comportement qui semble incohérent.

• Le mode debug ne change rien après activation : le cache n’a pas été vidé. PrestaShop sert une version compilée des pages ; videz le dossier var/cache pour forcer la prise en compte.
• L’erreur 500 persiste sans message détaillé : l’erreur survient avant le chargement du framework. Consultez alors le fichier de log du serveur (error_log) côté hébergeur.
• Une page blanche subsiste malgré le débogage : la limite mémoire PHP est peut-être atteinte ou l’affichage des erreurs est bloqué au niveau du serveur ; vérifiez la configuration PHP.
• Modification du fichier sans effet : le fichier a été édité au mauvais endroit ou pas renvoyé sur le serveur. Confirmez que /config/defines.inc.php de la boutique en ligne contient bien la valeur true.
• Oubli de désactivation : prenez l’habitude de couper le mode immédiatement après le diagnostic, jamais « plus tard ».

Si le diagnostic révèle un problème de fond qui dépasse le simple module à désactiver, ou si la moindre intervention dans les fichiers vous met mal à l’aise, l’accompagnement d’un spécialiste reste la voie la plus sûre pour éviter d’aggraver l’incident sur une boutique en activité.