Comment lire les logs d'erreurs PrestaShop comme un développeur

Pourquoi les logs d'erreurs PrestaShop sont importants

Chaque boutique PrestaShop génère des erreurs. Certaines sont des notices inoffensives qui n'affectent jamais vos clients. D'autres sont des défaillances critiques qui bloquent complètement votre processus de commande. La différence entre un propriétaire de boutique qui attend des jours l'aide du support et celui qui résout les problèmes en quelques minutes se résume souvent à une seule compétence : la lecture des logs d'erreurs.

Les logs d'erreurs sont la sortie de diagnostic de votre serveur et de votre application PrestaShop. Ils enregistrent chaque erreur PHP, chaque requête de base de données échouée, chaque problème de permission et chaque exception non interceptée. Quand quelque chose ne fonctionne pas, la réponse se trouve presque toujours dans un fichier de log. Le défi consiste à savoir où chercher, quoi chercher et comment interpréter ce que vous trouvez.

Ce guide couvre l'ensemble du paysage de la journalisation des erreurs dans PrestaShop. Vous apprendrez où se trouve chaque type de log, comment activer le rapport d'erreurs détaillé, comment lire les traces de pile (stack traces) et comment utiliser les outils en ligne de commande pour trouver l'aiguille dans la botte de foin. Que vous soyez en train de déboguer un écran blanc de la mort ou de traquer une erreur intermittente au moment du paiement, ce sont les connaissances dont vous avez besoin.

Où se trouvent les logs PrestaShop

PrestaShop génère des logs à plusieurs niveaux, et chaque niveau possède ses propres fichiers de logs. Comprendre quel log vérifier en premier vous fait gagner un temps considérable.

Logs applicatifs PrestaShop (var/logs)

À partir de PrestaShop 1.7, l'application utilise le framework Symfony pour son back office et le routage principal. Symfony écrit ses propres logs dans le répertoire var/logs/ situé à la racine de votre installation PrestaShop. Vous y trouverez des fichiers nommés selon l'environnement en cours :

var/logs/dev.log contient les logs lorsque PrestaShop fonctionne en mode développement. Ce fichier est extrêmement verbeux et enregistre tout, des décisions de routage aux requêtes de base de données. Il peut rapidement atteindre plusieurs centaines de mégaoctets.

var/logs/prod.log contient les logs du mode production. Ce fichier est beaucoup moins verbeux par défaut, n'enregistrant que les avertissements et les erreurs. C'est le fichier que vous devez vérifier en premier lorsque quelque chose ne fonctionne plus sur une boutique en ligne.

Ces fichiers de logs suivent le format Monolog, qui est la bibliothèque de journalisation standard de Symfony. Chaque ligne inclut un horodatage, le canal du log (comme request, security ou doctrine), le niveau de gravité et le message. Une entrée typique ressemble à ceci :

[2024-03-15 14:22:33] request.CRITICAL: Uncaught PHP Exception Symfony\Component\HttpKernel\Exception\NotFoundHttpException: "No route found for GET /admin/nonexistent" at /var/www/html/vendor/symfony/http-kernel/EventListener/RouterListener.php line 136

Les niveaux de gravité, du moins au plus sévère, sont : DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT et EMERGENCY. Lors du dépannage, filtrez d'abord par ERROR et CRITICAL.

Log d'erreurs PHP

PHP lui-même maintient un log d'erreurs distinct des logs applicatifs de PrestaShop. Ce log capture les erreurs qui se produisent avant l'initialisation du framework de journalisation de PrestaShop, ou les erreurs dans du code qui n'utilise pas le logger Symfony. L'emplacement de ce fichier dépend de la configuration de votre serveur.

Sur la plupart des serveurs Linux avec Apache, le log d'erreurs PHP se trouve à /var/log/php_errors.log ou /var/log/php/error.log. Sur les hébergements mutualisés avec cPanel, il se trouve souvent à /home/username/logs/error.log ou dans le répertoire public_html sous le nom error_log.

Vous pouvez trouver l'emplacement exact en vérifiant la configuration PHP. Créez un fichier PHP temporaire avec phpinfo(); et recherchez la directive error_log. Alternativement, exécutez php -i | grep error_log depuis la ligne de commande.

Les logs d'erreurs PHP capturent les erreurs fatales, les erreurs d'analyse, les avertissements et les notices. Une entrée d'erreur fatale ressemble généralement à ceci :

[15-Mar-2024 14:22:33 UTC] PHP Fatal error: Uncaught Error: Class 'SomeModule\SomeClass' not found in /var/www/html/modules/somemodule/somemodule.php:45

Logs du serveur web (Apache et Nginx)

Votre serveur web maintient son propre ensemble de logs, indépendants de PHP et de PrestaShop. Ces logs sont essentiels pour diagnostiquer les erreurs 500, les erreurs 404 et les problèmes de performance.

Les logs Apache se trouvent généralement à :

/var/log/apache2/error.log pour le log d'erreurs sur les systèmes Debian et Ubuntu.
/var/log/httpd/error_log pour le log d'erreurs sur les systèmes CentOS et RHEL.
/var/log/apache2/access.log pour le log d'accès, qui enregistre chaque requête HTTP.

Les logs Nginx se trouvent généralement à :

/var/log/nginx/error.log pour le log d'erreurs.
/var/log/nginx/access.log pour le log d'accès.

Si votre site utilise une configuration de virtual host, les logs peuvent se trouver à un emplacement spécifique au site, défini par la directive ErrorLog (Apache) ou error_log (Nginx) dans le fichier de votre virtual host.

Les logs d'erreurs du serveur web capturent des problèmes tels que les erreurs de permission refusée lorsque PHP tente d'écrire dans un répertoire, les erreurs de syntaxe de configuration après une modification du .htaccess, et les erreurs de timeout de proxy si vous utilisez PHP-FPM derrière Nginx. Ce sont les logs à vérifier lorsque vous voyez une erreur générique 500 Internal Server Error sans détails dans les logs PHP ou PrestaShop.

Logs legacy PrestaShop (Back Office)

PrestaShop maintient également une visionneuse de logs dans le back office sous Paramètres avancés > Logs. Cette interface affiche les entrées de log stockées dans la table ps_log de la base de données. Ces logs capturent les événements que PrestaShop enregistre explicitement, tels que les tentatives de connexion échouées, les erreurs d'installation de modules et les échecs d'envoi d'emails.

Bien que la visionneuse de logs du back office soit pratique, elle présente des limitations significatives. Elle ne capture pas les erreurs PHP, les erreurs du serveur web ni la plupart des erreurs fatales qui empêchent le chargement de la page. Considérez-la comme un complément aux logs basés sur les fichiers, pas comme un remplacement.

Activer le mode debug dans PrestaShop

Par défaut, PrestaShop fonctionne en mode production et masque les messages d'erreur détaillés aux visiteurs. C'est correct pour une boutique en ligne, mais cela rend le débogage pratiquement impossible. Lorsque quelque chose ne fonctionne plus, votre première étape devrait être d'activer le mode debug.

Méthode 1 : le fichier defines.inc.php

Ouvrez le fichier config/defines.inc.php et recherchez la ligne qui définit _PS_MODE_DEV_. Changez la valeur de false à true :

define('_PS_MODE_DEV_', true);

Ce seul changement a plusieurs effets. Le rapport d'erreurs PHP est réglé à son niveau maximum, affichant toutes les erreurs, avertissements et notices. La mise en cache des templates Smarty est désactivée, donc les modifications de templates apparaissent immédiatement. La barre de profilage Symfony apparaît en bas des pages du back office. Et surtout, les détails des erreurs sont affichés à l'écran au lieu d'afficher une page d'erreur générique.

Méthode 2 : le mode profilage de debug

Pour une analyse plus approfondie, vous pouvez également activer le profilage. Dans le même fichier, définissez :

define('_PS_DEBUG_PROFILING_', true);

Cela ajoute des informations détaillées de temps d'exécution et d'utilisation mémoire en bas de chaque page, vous montrant quels hooks prennent le plus de temps, quels modules consomment le plus de mémoire et combien de requêtes de base de données chaque page génère. C'est inestimable pour le débogage de performances mais ne doit jamais être laissé activé en production.

Avertissement de sécurité

Le mode debug expose des informations sensibles, notamment les chemins de fichiers, les identifiants de base de données dans les traces de pile et la structure interne de l'application. Ne laissez jamais le mode debug activé sur une boutique en production accessible au public. Si vous devez déboguer une boutique en ligne, envisagez de restreindre le mode debug à votre adresse IP en enveloppant la définition dans une vérification d'IP, ou utilisez un environnement de staging.

Lire les traces de pile (stack traces)

Lorsque PrestaShop rencontre une erreur fatale ou une exception non interceptée en mode debug, il affiche une trace de pile. Une trace de pile est un instantané de la chaîne d'appels qui a conduit à l'erreur, depuis le point de défaillance jusqu'au point d'entrée initial. Apprendre à lire les traces de pile est la compétence de débogage la plus précieuse que vous puissiez développer.

Anatomie d'une trace de pile

Une trace de pile PrestaShop typique ressemble à ceci :

PHP Fatal error: Uncaught TypeError: Argument 1 passed to Product::getProductProperties() must be of the type int, null given, called in /var/www/html/classes/Product.php on line 4523

Stack trace:
#0 /var/www/html/classes/Product.php(4523): Product::getProductProperties(NULL, Array)
#1 /var/www/html/modules/somemodule/somemodule.php(127): Product::getProductProperties(1, Array)
#2 /var/www/html/classes/Hook.php(523): SomeModule->hookDisplayHome(Array)
#3 /var/www/html/classes/Hook.php(460): Hook::coreCallHook(Object(SomeModule), 'hookDisplayHome', Array)
#4 /var/www/html/classes/Hook.php(408): Hook::exec('displayHome', Array)

Lisez la trace de pile de haut en bas. La première ligne vous indique ce qui s'est mal passé : une fonction attendait un entier mais a reçu null. La ligne #0 vous indique où l'erreur s'est produite. La ligne #1 vous indique ce qui a appelé le code à la ligne #0. La ligne #2 vous indique ce qui a appelé #1, et ainsi de suite.

Dans cet exemple, la chaîne est claire : PrestaShop a exécuté le hook displayHome, qui a appelé la méthode hookDisplayHome dans SomeModule, laquelle a appelé Product::getProductProperties() avec une valeur null là où un entier était attendu. Le bug se trouve dans le module à la ligne 127, où il transmet une valeur incorrecte.

Trouver le cadre pertinent

Les traces de pile dans PrestaShop peuvent être longues, parfois 20 ou 30 niveaux de profondeur. L'essentiel est de trouver le cadre qui contient votre code ou le module à l'origine du problème. Recherchez les chemins contenant /modules/ ou /themes/ car ce sont les sources les plus probables de bugs. Les cadres qui font référence à /classes/, /src/ ou /vendor/ correspondent au code principal de PrestaShop ou aux bibliothèques tierces, ce qui est moins susceptible d'être la source du problème, à moins que vous n'ayez modifié les fichiers du core.

Schémas d'erreurs courants dans PrestaShop

Après avoir lu des milliers de logs d'erreurs PrestaShop, certains schémas reviennent de manière récurrente. Reconnaître ces schémas vous permet de diagnostiquer les problèmes en quelques secondes au lieu de plusieurs heures.

Erreurs de classe introuvable

PHP Fatal error: Uncaught Error: Class 'ModuleName\ClassName' not found

Cela signifie que l'autoloader ne trouve pas la classe spécifiée. Les causes courantes incluent : un fichier vendor/autoload.php manquant (le module nécessite un composer install), une déclaration de namespace incorrecte, un fichier qui n'a pas été inclus dans le ZIP du module lors de l'installation, ou un problème de sensibilité à la casse sur les serveurs Linux où ClassName.php et classname.php sont des fichiers différents.

Erreurs de permission refusée

Warning: file_put_contents(/var/www/html/var/cache/prod/some_file): failed to open stream: Permission denied

Ces erreurs se produisent lorsque l'utilisateur du serveur web (généralement www-data sur Debian/Ubuntu ou apache sur CentOS) n'a pas les permissions d'écriture sur un fichier ou un répertoire. Corrigez cela en ajustant la propriété : chown -R www-data:www-data var/cache/ et les permissions : chmod -R 775 var/cache/.

Erreurs de limite mémoire

PHP Fatal error: Allowed memory size of 134217728 bytes exhausted (tried to allocate 65536 bytes)

Le nombre 134217728 octets correspond à 128 Mo, qui est la limite mémoire PHP par défaut. PrestaShop recommande au moins 256 Mo. Augmentez-la dans votre fichier php.ini : memory_limit = 512M. Si l'erreur persiste même avec des limites mémoire élevées, le code comporte probablement une fuite mémoire, souvent causée par le chargement de trop de produits ou catégories dans une seule requête sans pagination.

Erreurs de connexion à la base de données

Link to database cannot be established: SQLSTATE[HY000] [2002] Connection refused

Cela signifie que PrestaShop ne parvient pas à se connecter au serveur MySQL. Vérifiez que le serveur de base de données fonctionne, que les identifiants dans app/config/parameters.php sont corrects et que l'hôte de la base de données est accessible depuis le serveur web.

Erreurs de templates Smarty

SmartyException: Unable to load template file 'module:somemodule/views/templates/hook/display.tpl'

Le fichier de template est manquant, mal orthographié ou dans le mauvais répertoire. Vérifiez que le fichier existe au chemin attendu et que le nom du fichier correspond exactement, y compris la casse.

Erreurs de jeton CSRF

Invalid token. Please try to log in again.

Cette erreur apparaît dans le back office lorsqu'une soumission de formulaire inclut un jeton de sécurité expiré ou manquant. Cela se produit généralement lorsqu'une session expire pendant une longue session d'édition, lorsque plusieurs onglets sont ouverts sur la même page d'administration, ou lorsqu'un module génère ses URL de formulaire de manière incorrecte.

Utiliser grep pour trouver des erreurs

Lorsque les fichiers de logs sont volumineux, les parcourir manuellement est peu pratique. La commande grep est votre meilleure alliée pour trouver rapidement les entrées pertinentes.

Recherche basique d'erreurs

Pour trouver toutes les erreurs fatales dans le log d'erreurs PHP :

grep 'Fatal error' /var/log/php_errors.log

Pour trouver les erreurs provenant d'un module spécifique :

grep 'somemodule' /var/www/html/var/logs/prod.log

Pour trouver uniquement les erreurs du jour (en supposant le format de date dans le log) :

grep '2024-03-15' /var/www/html/var/logs/prod.log | grep 'ERROR\|CRITICAL'

Filtrage avancé

Pour voir les erreurs avec le contexte environnant (3 lignes avant et après chaque correspondance) :

grep -C 3 'Fatal error' /var/log/php_errors.log

Pour compter combien de fois chaque erreur unique se produit :

grep 'Fatal error' /var/log/php_errors.log | sort | uniq -c | sort -rn | head -20

Ce pipeline trie les erreurs, compte les doublons, trie par nombre décroissant et affiche les 20 premières. C'est incroyablement utile pour identifier les erreurs les plus fréquentes nécessitant une attention prioritaire.

Pour rechercher dans plusieurs fichiers de logs simultanément :

grep -r 'Fatal error' /var/log/ --include='*.log'

L'option -r effectue une recherche récursive, et --include limite la recherche aux fichiers avec l'extension .log.

Surveillance en temps réel des logs avec tail -f

Lorsque vous déboguez activement un problème, vous devez voir les erreurs au moment où elles se produisent. La commande tail -f suit un fichier de log en temps réel, affichant les nouvelles entrées au fur et à mesure qu'elles sont écrites.

Surveillance basique en temps réel

Pour surveiller le log de production PrestaShop en temps réel :

tail -f /var/www/html/var/logs/prod.log

Pour surveiller le log d'erreurs PHP :

tail -f /var/log/php_errors.log

Pour surveiller plusieurs fichiers de logs en même temps :

tail -f /var/www/html/var/logs/prod.log /var/log/php_errors.log /var/log/apache2/error.log

Surveillance filtrée en temps réel

Pour ne voir que les entrées de niveau erreur en temps réel, combinez tail avec grep :

tail -f /var/www/html/var/logs/prod.log | grep --line-buffered 'ERROR\|CRITICAL'

L'option --line-buffered est importante ici. Sans elle, grep met sa sortie en tampon et vous risquez de ne pas voir les correspondances immédiatement.

Pour mettre en surbrillance des mots-clés spécifiques tout en affichant l'ensemble de la sortie :

tail -f /var/www/html/var/logs/prod.log | grep --color=always -E 'ERROR|CRITICAL|$'

Cela met en surbrillance ERROR et CRITICAL en couleur tout en continuant à afficher toutes les lignes.

Le workflow de débogage

Le workflow de débogage le plus efficace combine la surveillance en temps réel avec les tests actifs. Ouvrez une fenêtre de terminal avec tail -f en cours d'exécution sur les fichiers de logs pertinents. Dans votre navigateur, reproduisez l'action qui cause l'erreur. Observez le terminal pour voir les nouvelles entrées de log qui apparaissent au moment exact où vous déclenchez le problème. Cette approche élimine les conjectures et vous montre précisément ce qui se passe lorsque l'erreur survient.

Rotation et gestion des logs

Les fichiers de logs grossissent continuellement et peuvent consommer tout l'espace disque disponible s'ils ne sont pas gérés. La plupart des serveurs Linux utilisent logrotate pour gérer cela automatiquement, mais les propres logs de PrestaShop dans var/logs/ peuvent ne pas être inclus dans la configuration par défaut de logrotate.

Comprendre logrotate

L'utilitaire logrotate s'exécute quotidiennement (généralement via cron) et gère la rotation, la compression et la suppression des fichiers de logs. Les fichiers de configuration se trouvent dans /etc/logrotate.d/. La rotation des logs Apache et Nginx est généralement configurée par défaut.

Pour le répertoire var/logs de PrestaShop, vous devrez peut-être créer une configuration logrotate personnalisée :

/var/www/html/var/logs/*.log {
  daily
  missingok
  rotate 14
  compress
  delaycompress
  notifempty
  create 0640 www-data www-data
}

Cela effectue une rotation quotidienne des logs, conserve 14 jours d'historique, compresse les anciens logs et crée de nouveaux fichiers de logs avec les permissions correctes.

Nettoyage manuel des logs

Si un fichier de log est devenu extrêmement volumineux et que vous devez le vider sans perdre le descripteur de fichier (important si un processus est en train d'y écrire activement) :

truncate -s 0 /var/www/html/var/logs/prod.log

Ne supprimez pas le fichier pour le recréer, car tout processus ayant le fichier ouvert continuera d'écrire dans l'inode du fichier supprimé jusqu'à ce qu'il soit redémarré. L'approche par truncate vide le contenu tout en préservant l'inode.

Comprendre les contextes d'erreurs spécifiques à PrestaShop

Les erreurs PrestaShop sont souvent accompagnées d'un contexte unique à la plateforme. Comprendre ce contexte vous aide à localiser et corriger les problèmes plus rapidement.

Erreurs liées aux hooks

Lorsqu'une erreur se produit à l'intérieur d'un hook, la trace de pile inclura des références à Hook::exec() et Hook::coreCallHook(). Le nom du hook vous indique exactement à quel moment du processus de rendu de la page l'erreur se produit. Par exemple, les erreurs displayHome se produisent sur la page d'accueil, les erreurs actionValidateOrder se produisent pendant le processus de commande, et les erreurs displayBackOfficeHeader se produisent lors du chargement de n'importe quelle page du back office.

Si une erreur de hook fait planter une page, vous pouvez temporairement désactiver le module fautif depuis la base de données :

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

Cela vous permet d'accéder au back office pour diagnostiquer et corriger correctement le problème.

Conflits d'overrides

Le système d'overrides de PrestaShop permet aux modules d'étendre les classes du core, mais des conflits surviennent lorsque deux modules surchargent la même classe. L'erreur apparaît généralement sous forme de conflit de signature de méthode ou de changement de comportement inattendu. Vérifiez le répertoire override/ pour voir quels overrides sont actifs, et vérifiez le fichier cache/class_index.php qui mappe les classes vers leurs fichiers d'override. Supprimer ce fichier cache force PrestaShop à régénérer la carte des overrides.

Erreurs liées au cache

De nombreuses erreurs PrestaShop sont causées par des fichiers de cache obsolètes. Si vous voyez des erreurs qui ne correspondent pas au code actuel (par exemple, une erreur faisant référence à un numéro de ligne qui n'existe pas dans le fichier), le cache est probablement périmé. Videz-le en supprimant le contenu de var/cache/prod/ et var/cache/dev/. Sur PrestaShop 1.6, videz plutôt cache/smarty/compile/ et cache/smarty/cache/.

Erreurs d'installation et de mise à jour de modules

Les installations de modules peuvent échouer silencieusement, laissant le module dans un état partiellement installé. Vérifiez var/logs/prod.log pour les entrées correspondant à l'horodatage de l'installation. Les problèmes courants incluent les tables de base de données manquantes (le SQL de la méthode install() du module a échoué), les hooks manquants (l'appel registerHook() a échoué) et les erreurs d'entrée en double dans la table ps_authorization_role lors de la réinstallation d'un module qui n'a pas été complètement désinstallé.

Construire une checklist de débogage

Lorsque vous rencontrez une erreur PrestaShop, suivez cette checklist systématique pour trouver la cause efficacement :

Premièrement, identifiez le type d'erreur. S'agit-il d'un écran blanc (erreur 500), d'un message d'erreur spécifique, d'une mise en page cassée ou d'un comportement inattendu ? Chaque type pointe vers des fichiers de logs différents.

Deuxièmement, vérifiez d'abord le log le plus spécifique. Pour les erreurs PHP, vérifiez le log d'erreurs PHP. Pour les erreurs HTTP, vérifiez le log d'erreurs du serveur web. Pour les erreurs applicatives, vérifiez var/logs/prod.log.

Troisièmement, activez le mode debug si les logs ne révèlent pas suffisamment d'informations. Changez _PS_MODE_DEV_ à true et reproduisez l'erreur.

Quatrièmement, utilisez tail -f sur les logs pertinents et reproduisez l'erreur dans votre navigateur. Cela vous donne une vue en temps réel de ce qui se passe exactement.

Cinquièmement, lisez la trace de pile de haut en bas. Trouvez le cadre qui fait référence à votre module ou au code de votre thème. C'est là que le correctif doit être appliqué.

Sixièmement, recherchez le message d'erreur dans les issues GitHub de PrestaShop et sur les forums. Il y a de fortes chances que quelqu'un ait déjà rencontré et résolu le même problème auparavant.

Septièmement, après avoir appliqué un correctif, videz tous les caches et surveillez les logs pour confirmer que l'erreur a disparu. Un correctif qui ne produit pas un log propre n'est pas un correctif complet.

Résumé

Lire les logs d'erreurs PrestaShop n'est pas un art mystérieux réservé aux développeurs seniors. C'est une compétence pratique fondée sur le fait de savoir où vivent les logs, comment les filtrer et comment interpréter leur contenu. Les logs dans var/logs/, le log d'erreurs PHP et le log du serveur web remplissent chacun un rôle différent et, ensemble, vous donnent une image complète de tout problème. Activer le mode debug vous donne des messages d'erreur détaillés. Les traces de pile vous montrent la chaîne exacte des appels de fonctions qui a conduit à la défaillance. Des outils comme grep et tail -f permettent de trouver et surveiller les erreurs efficacement, même dans des fichiers de logs volumineux et très sollicités. Maîtrisez ces techniques et vous résoudrez les problèmes plus rapidement, avec moins de frustration et beaucoup moins de dépendance au support externe.