Page blanche PrestaShop après mise à jour du noyau : Guide de récupération

Pourquoi les pages blanches surviennent après les mises à jour PrestaShop

Une page blanche, souvent appelée l'écran blanc de la mort (WSOD pour White Screen of Death), est l'un des problèmes les plus courants et les plus alarmants auxquels les propriétaires de boutiques PrestaShop sont confrontés après la mise à jour du logiciel de base. Vous lancez une mise à jour de la version 1.7.8.7 vers 1.7.8.8, ou de 8.1.0 vers 8.1.5, le processus semble se terminer, puis votre boutique entière, tant le front office que le back office, n'affiche plus rien d'autre qu'un écran blanc. Aucun message d'erreur, aucun contenu partiel, juste le néant.

Comprendre pourquoi cela se produit nécessite de comprendre ce que fait une mise à jour du noyau PrestaShop. Le processus de mise à jour remplace des centaines de fichiers PHP, modifie des tables de base de données, régénère les index de classes, vide les caches et exécute potentiellement des requêtes de migration. Toute défaillance à n'importe quel point de cette chaîne peut laisser la boutique dans un état incohérent où PHP rencontre une erreur fatale mais n'a aucun moyen de l'afficher car le rapport d'erreurs est désactivé en mode production.

Les causes les plus courantes se répartissent en plusieurs catégories : des modules incompatibles qui référencent des classes de base supprimées ou modifiées, des incompatibilités de version PHP entre l'ancienne et la nouvelle version de PrestaShop, des conflits de fichiers de surcharge où les surcharges personnalisées entrent en collision avec des fichiers de base modifiés, des ressources serveur insuffisantes provoquant l'interruption de la mise à jour en cours de processus, et des échecs de migration de base de données qui laissent les tables dans un état incohérent.

Étape 1 : Activer le mode débogage

La toute première action face à une page blanche est de rendre les erreurs visibles. PrestaShop supprime l'affichage des erreurs en mode production pour éviter d'exposer des informations sensibles aux visiteurs. Vous devez temporairement activer le mode débogage pour voir ce qui ne va réellement pas.

La méthode la plus rapide consiste à modifier le fichier /config/defines.inc.php. Cherchez la ligne qui définit _PS_MODE_DEV_ et changez-la :

define('_PS_MODE_DEV_', true);

Si vous ne pouvez pas accéder aux fichiers via FTP ou SSH parce que votre panneau d'hébergement est également inaccessible, certains hébergeurs offrent un gestionnaire de fichiers via leur panneau de contrôle (cPanel, Plesk, DirectAdmin) qui fonctionne indépendamment de votre installation PrestaShop.

Dans PrestaShop 8.x, vous pouvez également activer le mode débogage via le fichier .env dans le répertoire racine. Changez APP_ENV=prod en APP_ENV=dev et définissez APP_DEBUG=1. Cela active la barre d'outils de débogage Symfony et les pages d'erreur détaillées.

Après avoir activé le mode débogage, rechargez la page. Au lieu d'un écran blanc, vous devriez maintenant voir un message d'erreur détaillé avec un chemin de fichier, un numéro de ligne et une trace de pile. Ce message d'erreur est la clé pour diagnostiquer et résoudre le problème.

Étape 2 : Vérifier les journaux d'erreurs

Si l'activation du mode débogage affiche toujours une page blanche (ce qui peut arriver si l'erreur survient avant même que PHP ne charge le framework PrestaShop), vérifiez directement les journaux d'erreurs de votre serveur.

Sur les serveurs Apache, le journal d'erreurs se trouve généralement à /var/log/apache2/error.log ou /var/log/httpd/error_log. Sur Nginx avec PHP-FPM, vérifiez /var/log/nginx/error.log et /var/log/php-fpm/error.log (ou /var/log/php8.1-fpm.log selon votre version de PHP). Sur un hébergement mutualisé, les journaux d'erreurs sont généralement accessibles via le panneau de contrôle de l'hébergement ou dans un répertoire logs au sein de votre compte d'hébergement.

PrestaShop maintient également ses propres fichiers de journalisation dans le répertoire /var/logs/ (PrestaShop 1.7) ou le répertoire /var/log/ (PrestaShop 8.x). Cherchez les fichiers nommés avec la date du jour. Ces journaux basés sur Symfony peuvent contenir des informations détaillées sur ce qui a mal tourné pendant le processus de mise à jour.

De plus, vérifiez le répertoire /log/ à la racine de votre PrestaShop pour tout fichier de journal d'erreurs. Certaines versions de PrestaShop y écrivent les erreurs critiques lorsqu'elles ne peuvent pas les afficher à l'écran.

Cause courante 1 : Modules incompatibles

Les modules sont la cause la plus fréquente des pages blanches après les mises à jour. Un module qui fonctionnait parfaitement sur PrestaShop 1.7.8.7 peut faire planter toute la boutique sur 1.7.8.8 s'il utilise des classes internes du noyau ou des méthodes qui ont changé lors de la mise à jour.

Le message d'erreur ressemble généralement à : Fatal error: Class 'SomeClassName' not found ou Fatal error: Call to undefined method ClassName::methodName() ou Fatal error: Declaration of ModuleClass::hookMethod() must be compatible with CoreClass::hookMethod().

Pour corriger cela, vous devez identifier et désactiver le module problématique. Si vous pouvez accéder au back office (parfois seul le front office plante), allez dans Modules et désactivez les modules récemment installés ou mis à jour un par un jusqu'à ce que le problème se résolve.

Si le back office est également inaccessible, désactivez les modules via la base de données. Connectez-vous à votre base de données en utilisant phpMyAdmin ou un client MySQL et exécutez :

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

Si vous ne savez pas quel module cause le problème, vous pouvez désactiver tous les modules tiers d'un coup en mettant leur colonne active à 0. D'abord, identifiez quels modules sont tiers en vérifiant le répertoire /modules/ pour les modules non-PrestaShop. Puis désactivez-les sélectivement.

Une approche plus radicale consiste à renommer le répertoire du module. Par exemple, renommez /modules/somemodule/ en /modules/somemodule_disabled/. PrestaShop ne peut pas charger un module dont le répertoire ne correspond pas à son nom enregistré, le désactivant effectivement sans toucher à la base de données.

Cause courante 2 : Incompatibilité de version PHP

Chaque version de PrestaShop requiert une plage de versions PHP spécifique. PrestaShop 1.7.6 et antérieur nécessitent PHP 7.1 à 7.3. PrestaShop 1.7.7 à 1.7.8 supportent PHP 7.2 à 8.0. PrestaShop 8.0 nécessite PHP 7.2 à 8.1. PrestaShop 8.1 nécessite PHP 8.0 à 8.2. PrestaShop 9.0 nécessite PHP 8.1 ou supérieur.

Si votre environnement d'hébergement a changé de version PHP pendant ou en parallèle de la mise à jour PrestaShop, vous pouvez rencontrer des erreurs de syntaxe ou des appels de fonctions dépréciées. Les erreurs courantes de compatibilité PHP incluent : Deprecated: Function create_function() is deprecated (PHP 7.2+ avec du code écrit pour PHP 5.x), Fatal error: Uncaught Error: Call to undefined function mysql_connect() (PHP 7.0+ a supprimé l'extension mysql), et Fatal error: Array and string offset access syntax with curly braces is no longer supported (PHP 8.0+).

Vérifiez votre version PHP actuelle en regardant la sortie de phpinfo() ou en exécutant php -v en ligne de commande. Si la version est en dehors de la plage supportée pour votre version de PrestaShop, basculez vers une version PHP compatible via le panneau de contrôle de votre hébergement.

Cause courante 3 : Conflits de surcharges

Le système de surcharge de PrestaShop permet aux modules et aux développeurs de modifier le comportement du noyau en plaçant des fichiers de classes modifiés dans le répertoire /override/. Lors d'une mise à jour, les classes du noyau changent, mais les fichiers de surcharge restent. Si une surcharge référence une signature de méthode qui a changé, une propriété qui a été supprimée ou une classe qui a été renommée, la surcharge provoque une erreur fatale.

Le fichier d'index de classes à /var/cache/prod/class_index.php (ou /cache/class_index.php sur les versions plus anciennes) fait correspondre les noms de classes à leurs emplacements de fichiers, y compris les surcharges. Un index de classes périmé ou corrompu peut charger le mauvais fichier pour une classe, causant des plantages immédiats.

Pour tester si les surcharges sont le problème, désactivez temporairement le système de surcharge. Éditez /config/defines.inc.php et ajoutez ou modifiez :

define('_PS_HOST_MODE_', false);

Puis supprimez le fichier d'index de classes pour forcer PrestaShop à le régénérer sans surcharges. Si la boutique se charge après cette modification, le problème se trouve dans l'un de vos fichiers de surcharge.

Pour identifier la surcharge problématique spécifique, regardez dans les répertoires /override/classes/ et /override/controllers/. Supprimez les fichiers de surcharge un par un, en supprimant l'index de classes après chaque suppression, jusqu'à ce que vous trouviez celui qui cause le plantage. Une fois identifié, soit mettez à jour la surcharge pour qu'elle soit compatible avec la nouvelle version du noyau, soit supprimez-la entièrement si elle n'est plus nécessaire.

Cause courante 4 : Cache et fichiers compilés

PrestaShop génère des templates Smarty compilés, des caches de conteneur Symfony, des cartes de classes et divers autres fichiers en cache qui deviennent invalides après une mise à jour. Si le processus de mise à jour n'a pas correctement vidé ces caches, la boutique tente d'utiliser des fichiers en cache qui référencent l'ancienne structure de code.

Videz tous les caches manuellement en supprimant le contenu de ces répertoires (supprimez le contenu, pas les répertoires eux-mêmes) :

/var/cache/prod/ et /var/cache/dev/ pour le cache Symfony. Supprimez tout à l'intérieur de ces répertoires. PrestaShop les régénérera au prochain chargement de page.

/cache/smarty/compile/ et /cache/smarty/cache/ pour les caches de templates Smarty. Les templates compilés périmés sont une cause très courante de pages blanches après les mises à jour.

/var/cache/prod/class_index.php (ou /cache/class_index.php) pour la carte des classes. Ce fichier doit être régénéré après toute mise à jour.

Sur les configurations PHP-FPM, réinitialisez également OPcache. OPcache stocke le bytecode PHP compilé en mémoire, et il peut servir l'ancien code même après que les fichiers ont été remplacés. Redémarrez le service PHP-FPM, ou si vous ne pouvez pas le faire, créez un petit fichier PHP qui appelle opcache_reset() et accédez-y via votre navigateur.

Cause courante 5 : Échecs de migration de base de données

Les mises à jour PrestaShop incluent souvent des modifications de schéma de base de données : nouvelles colonnes, index modifiés, nouvelles tables ou migrations de données. Si le processus de mise à jour a été interrompu (timeout, limite de mémoire, coupure de connexion), la base de données peut se trouver dans un état partiellement migré.

Vérifiez la base de données PrestaShop dans la table ps_configuration et cherchez la valeur PS_VERSION_DB. Si cette valeur ne correspond pas à la version des fichiers sur le disque, la mise à jour ne s'est pas terminée correctement. PrestaShop peut tenter de relancer les migrations au chargement suivant, ou simplement échouer.

Les échecs de migration de base de données sont les plus difficiles à récupérer sans sauvegarde. Si vous disposez d'une sauvegarde de la base de données d'avant la mise à jour, la restaurer et relancer la mise à jour est souvent le chemin le plus sûr. Si vous n'avez pas de sauvegarde, vous devrez peut-être appliquer manuellement les fichiers de migration SQL manquants qui se trouvent dans le répertoire /install/upgrade/sql/.

Procédure de récupération étape par étape

Suivez cette séquence lors de la récupération d'une page blanche après une mise à jour du noyau. L'ordre est important car chaque étape soit résout le problème, soit élimine une cause possible.

Étape 1 : Activez le mode débogage dans /config/defines.inc.php en mettant _PS_MODE_DEV_ à true. Rechargez la page et lisez le message d'erreur.

Étape 2 : Supprimez le contenu de /var/cache/prod/, /var/cache/dev/, /cache/smarty/compile/ et /cache/smarty/cache/. Supprimez class_index.php. Rechargez la page.

Étape 3 : Si l'erreur pointe vers un module spécifique, désactivez ce module en renommant son répertoire ou en mettant active = 0 dans la table de base de données ps_module. Rechargez la page.

Étape 4 : Si l'erreur pointe vers un fichier de surcharge, déplacez le contenu du répertoire /override/ vers un emplacement de sauvegarde temporaire. Supprimez à nouveau class_index.php. Rechargez la page.

Étape 5 : Vérifiez que votre version PHP est compatible avec la version PrestaShop vers laquelle vous avez fait la mise à jour. Vérifiez phpinfo() ou php -v. Changez de version PHP si nécessaire.

Étape 6 : Vérifiez les permissions de fichiers. Le processus de mise à jour peut avoir créé des fichiers avec une propriété incorrecte. Tous les fichiers PrestaShop doivent être lisibles par l'utilisateur du serveur web, et les répertoires /var/, /cache/, /img/, /upload/, /download/, /translations/, /themes/ et /modules/ doivent être accessibles en écriture.

Étape 7 : Si rien de ce qui précède ne résout le problème et que vous disposez d'une sauvegarde de la base de données, restaurez la base de données et les fichiers à partir de la sauvegarde, puis tentez à nouveau la mise à jour après avoir résolu les problèmes identifiés lors du diagnostic.

Procédure de mise à jour sécurisée pour les futures mises à jour

La prévention est bien meilleure que la récupération. Suivez cette procédure pour chaque mise à jour du noyau PrestaShop afin de minimiser le risque de pages blanches et de perte de données.

Avant la mise à jour : Créez une sauvegarde complète à la fois de la base de données et de tous les fichiers. Pas seulement la base de données, pas seulement les fichiers, mais les deux. Stockez ces sauvegardes dans un emplacement en dehors de votre compte d'hébergement si possible. Testez que vous pouvez réellement restaurer à partir de ces sauvegardes avant de procéder.

Désactivez tous les modules tiers. C'est la mesure la plus efficace que vous puissiez prendre pour prévenir les pages blanches. Les modules natifs (ceux livrés avec PrestaShop) sont conçus pour être compatibles avec la mise à jour, mais les modules tiers ne sont pas garantis de l'être. Désactivez-les avant la mise à jour et réactivez-les un par un après, en testant la boutique après chaque réactivation.

Désactivez le système de surcharge. Si vous avez des surcharges personnalisées, désactivez-les avant la mise à jour. Réévaluez chaque surcharge après la mise à jour pour déterminer si elle est toujours compatible et toujours nécessaire.

Lisez les notes de version. Chaque version de PrestaShop inclut des notes sur les exigences de compatibilité, les problèmes connus et les changements avec rupture de compatibilité. Lisez-les avant de mettre à jour, pas après que quelque chose ait cassé.

Mettez la boutique en mode maintenance. Cela empêche les clients de passer des commandes pendant la mise à jour et de rencontrer des erreurs. Naviguez vers Paramètres de la boutique, Général, Maintenance dans le back office et activez le mode maintenance.

Pendant la mise à jour : Surveillez le processus de mise à jour. Ne fermez pas l'onglet du navigateur et ne naviguez pas ailleurs. Si la mise à jour prend plus de temps que prévu, vérifiez les journaux d'erreurs de votre serveur pour les erreurs de timeout ou de mémoire. Si le processus semble bloqué, attendez au moins 10 minutes avant d'entreprendre toute action, car les grandes boutiques peuvent avoir des migrations de base de données significatives à traiter.

Après la mise à jour : Videz tous les caches. Vérifiez que le back office se charge correctement. Vérifiez le front office. Réactivez les modules un par un, en vérifiant la boutique après chacun. Réactivez les surcharges une par une le cas échéant. Désactivez le mode maintenance. Surveillez les journaux d'erreurs pendant les 24 heures suivantes.

Stratégies de retour en arrière

Lorsque la récupération n'est pas possible ou prend trop de temps, revenir à la version précédente peut être la meilleure option. Cependant, PrestaShop ne dispose pas d'un mécanisme de retour en arrière intégré, vous devez donc planifier cette possibilité avant de commencer la mise à jour.

Retour complet depuis une sauvegarde : Restaurez à la fois la base de données et les fichiers à partir de votre sauvegarde d'avant la mise à jour. C'est l'approche la plus propre mais elle nécessite d'avoir fait une sauvegarde complète avant la mise à jour. Après la restauration, vérifiez que la boutique fonctionne correctement et qu'aucune commande ou donnée client créée pendant la période de mise à jour échouée n'est perdue (si la boutique était en mode maintenance, rien n'aurait dû changer).

Retour partiel des fichiers : Si seuls les fichiers sont corrompus mais que la base de données est intacte, vous pouvez remplacer les fichiers PrestaShop par la version précédente tout en conservant la base de données actuelle. Téléchargez la version précédente exacte de PrestaShop depuis l'archive officielle des versions, extrayez-la et écrasez les fichiers sur votre serveur. Conservez vos modules personnalisés, thèmes et fichiers de configuration. Cette approche est risquée car la base de données peut avoir été partiellement migrée, créant une incohérence entre les fichiers et le schéma de la base de données.

Correction directe : Parfois le chemin le plus rapide n'est pas de revenir en arrière mais de corriger l'erreur spécifique. Si l'erreur est causée par un seul module ou surcharge incompatible, corriger ou supprimer ce seul composant peut prendre quelques minutes comparé à des heures pour un retour complet. Cette approche est la meilleure lorsque vous avez clairement identifié la cause à partir du message d'erreur.

L'importance des sauvegardes de base de données

Chaque section de ce guide mentionne les sauvegardes, et pour une bonne raison. Une base de données PrestaShop contient chaque produit, chaque commande, chaque compte client, chaque paramètre de configuration et chaque contenu de votre boutique. La perdre signifie perdre les données de votre entreprise.

Les sauvegardes quotidiennes automatisées ne sont pas optionnelles pour une boutique PrestaShop en production. Configurez le système de sauvegarde de votre hébergeur, utilisez un module de sauvegarde de base de données, ou configurez une tâche cron qui exécute mysqldump à intervalles réguliers. Stockez les sauvegardes à plusieurs emplacements. Testez votre procédure de restauration périodiquement pour vous assurer que les sauvegardes sont réellement utilisables.

Avant toute mise à jour, créez une sauvegarde manuelle en plus de vos sauvegardes automatisées. Nommez-la clairement avec la date et la version PrestaShop, afin de pouvoir l'identifier immédiatement si vous devez la restaurer.

Quand faire appel à un professionnel

Si vous avez suivi toutes les étapes de ce guide et faites toujours face à une page blanche, ou si les messages d'erreur pointent vers des problèmes profonds du noyau nécessitant des corrections au niveau du code, il est peut-être temps de faire appel à un développeur PrestaShop. Fournissez-lui les messages d'erreur que vous avez recueillis, les versions de PrestaShop impliquées (avant et après la mise à jour), votre version PHP et toutes les actions que vous avez déjà entreprises. Ces informations réduiront considérablement le temps nécessaire pour diagnostiquer et résoudre le problème.

Tenter de modifier manuellement les fichiers du noyau PrestaShop sans comprendre l'architecture du framework peut créer des problèmes supplémentaires. Si le message d'erreur fait référence aux conteneurs Symfony, à l'injection de dépendances ou à la configuration du kernel, ce sont des domaines où des modifications incorrectes peuvent provoquer des défaillances en cascade.