Sur un projet PHP, l’instant où tout se fige avec une page blanche ou un simple « erreur 500 » arrive toujours au pire moment. Sans messages d’erreur visibles ni logs exploitables, le debug PHP devient vite un exercice de divination. Entre l’affichage navigateur à activer ponctuellement en développement et l’affichage serveur via les journaux d’erreurs, la clé consiste à comprendre où régler quoi dans la configuration PHP et comment ne pas exposer trop d’informations en production. Les mêmes paramètres reviennent partout, en particulier ini_set display_errors, error_reporting et la gestion des logs, mais leur portée (par script, par vhost, globalement dans php.ini) change fortement leurs effets.
Pour un profil comme Clara, développeuse qui jongle entre un homelab, une préproduction un peu bricolée et un mutualisé chez un hébergeur, les besoins ne sont pas les mêmes selon l’environnement. En local, elle veut absolument tout voir remonter dans le navigateur pour corriger son code en direct. Sur le serveur, elle préfère que les erreurs PHP alimentent un fichier de log bien rangé, pendant que les utilisateurs voient une page propre. Ce texte détaille justement comment activer affichage erreur dans le code, dans php.ini, au niveau Apache/Nginx, mais aussi comment construire un routage propre vers des fichiers de log et des gestionnaires personnalisés. L’objectif est simple : ne plus perdre de temps à chercher « pourquoi rien ne s’affiche », tout en gardant un niveau de sécurité correct une fois en ligne.
En bref
- Afficher une erreur PHP dans le navigateur passe par le duo ini_set display_errors et error_reporting(E_ALL), utile surtout en environnement de développement.
- L’affichage serveur doit s’appuyer sur des fichiers de log erreurs PHP, avec
log_errorsactivé et unerror_logbien choisi. - La configuration PHP peut se faire à plusieurs niveaux : php.ini, .htaccess, directives de vhost, voire au sein du script.
- Un gestionnaire d’erreurs personnalisé permet de formater les messages d’erreur, filtrer les niveaux et router ce qui doit partir dans les logs.
- En production, l’affichage erreur doit rester désactivé dans le navigateur au profit d’une journalisation complète côté serveur.
Afficher erreur PHP dans le navigateur avec display_errors et error_reporting
Pour s’assurer que les erreurs PHP apparaissent bien à l’écran pendant le développement, le réflexe à avoir reste d’activer explicitement l’affichage erreur dans le script. Cette approche localise la configuration à une zone précise du code, ce qui évite d’ouvrir les vannes partout sur le serveur. Dans un fichier de bootstrap ou d’index utilisé uniquement en environnement de dev, quelques lignes suffisent à rendre les problèmes visibles dès le premier rafraîchissement.
Le bloc minimal ressemble par exemple à ceci :
ini_set('display_errors', 1);
ini_set('display_startup_errors', 1);
error_reporting(E_ALL);
Ce trio impose un debug PHP verbeux, y compris pour les erreurs de démarrage de PHP. L’usage de error_reporting(E_ALL) reste recommandé tant que l’application est en phase de construction, car masquer les avertissements dès le début cache souvent des problèmes de qualité qui finiront par ressortir plus tard. Une fois le code stabilisé, on peut réduire le bruit en excluant certains niveaux, mais mieux vaut régler le fond du problème plutôt que de tout filtrer.
Clara, par exemple, place ce bloc dans un fichier config.dev.php inclus uniquement sur son environnement local via une variable d’environnement. Sur le même code déployé chez le client, ce fichier n’existe pas et aucune affichage navigateur des erreurs n’est activée. Ce genre de séparation évite les mauvaises surprises lorsque l’environnement « de test » d’un client se retrouve soudain accessible au public.
Configurer php.ini pour un affichage d’erreur PHP permanent en environnement de test
Dès que plusieurs développeurs partagent la même machine ou le même conteneur, régler ini_set display_errors dans chaque script devient vite répétitif. Dans ce cas, un réglage directement dans le php.ini dédié au serveur de développement simplifie beaucoup la vie. On se contente de définir les directives une seule fois pour l’ensemble des projets qui tournent dessus, à condition que la séparation avec les environnements sensibles soit bien gérée.
Les lignes les plus utilisées ressemblent à ce qui suit :
display_errors = On
display_startup_errors = On
error_reporting = E_ALL
Après redémarrage d’Apache, Nginx ou PHP-FPM selon la pile utilisée, tout script sans override local bénéficiera de cette configuration. Il arrive que l’on tombe sur des hébergeurs qui forcent display_errors = Off et ignorent les demandes dans le code ; dans ce cas, la seule option consiste parfois à passer par un fichier .htaccess ou un panneau de configuration spécifique. Les panneaux Plesk ou cPanel, par exemple, exposent souvent ces paramètres dans un menu dédié sans demander d’édition manuelle du fichier.
Activer l’affichage des messages d’erreur PHP au niveau serveur (php.ini, .htaccess, vhost)
Quand on parle d’affichage serveur, on sort du simple script isolé pour toucher la configuration globale du runtime PHP. Sur une machine gérée en propre, le fichier php.ini reste le point central, mais les environnements mutualisés et les conteneurs applicatifs rajoutent parfois une couche Apache ou Nginx. Concrètement, cette diversité de points de configuration explique pourquoi certains paramètres semblent « ne pas marcher » alors qu’ils sont écrits au bon endroit.
Sur un Apache classique, il est possible d’activer ou désactiver les messages d’erreur via un fichier .htaccess :
php_value display_errors 1
php_value display_startup_errors 1
php_value error_reporting E_ALL
Cette technique reste pratique pour un projet isolé hébergé parmi d’autres, notamment chez les hébergeurs mutualisés. Sur Nginx couplé à PHP-FPM, on ne dispose pas de .htaccess, et la configuration se fait plutôt via un fichier dédié ou un override d’ini dans /etc/php/*/fpm/conf.d/. Le plus propre consiste à documenter où chaque directive est définie et à ne garder qu’un seul endroit responsable de l’affichage erreur pour chaque environnement.
Tableau comparatif des principaux niveaux de configuration PHP
Pour éviter de se perdre entre toutes les options, un tableau récapitulatif aide souvent à trancher où régler le comportement des erreurs PHP selon le contexte.
| Niveau de configuration | Portée principale | Avantages | Limites / risques |
|---|---|---|---|
| php.ini global | Tous les sites / conteneurs utilisant cette instance PHP | Configuration centralisée, cohérente pour tout l’environnement | Un mauvais réglage peut exposer des messages d’erreur sur plusieurs applications sensibles |
| Fichier .htaccess / vhost Apache | Un site ou un VirtualHost précis | Adapté à un projet spécifique sans impacter les autres | Risque de conflit avec php.ini, directives parfois désactivées chez certains hébergeurs |
| Fichiers .ini dans conf.d | Profil dédié (CLI, FPM, Apache module) | Permet de différencier dev, staging et production par profil PHP | Nécessite une bonne connaissance de la pile pour éviter les doublons |
| ini_set() dans le code | Script ou bloc de code précis | Contrôle très fin, idéal pour le debug ponctuel | Facile à oublier en production, peut être désactivé par la configuration centrale |
Dans une PME qui héberge plusieurs projets internes sur le même cluster, la combinaison la plus raisonnable reste souvent : php.ini verrouillé avec display_errors = Off, puis configuration spécifique en dev via un autre conteneur ou un autre profil PHP. Tout ce qui déroge à cette règle doit être soigneusement documenté, au même titre que les règles de firewall ou de sauvegarde.
Rediriger les erreurs PHP vers un fichier de log côté serveur
Dès que l’application commence à recevoir du trafic réel, afficher chaque erreur PHP dans le navigateur devient un risque inutile. Non seulement les visiteurs n’ont pas envie de voir la stack trace complète, mais ces détails techniques donnent aussi beaucoup d’informations aux attaquants potentiels. A ce stade, l’affichage serveur doit passer en mode silencieux vers des fichiers de logs consultables uniquement par les administrateurs.
Pour cela, on active la journalisation dans PHP :
log_errors = On
error_log = /var/log/php/error.log
Sur un système Linux correctement structuré, il reste pertinent de placer ce fichier dans un répertoire déjà pris en charge par la rotation de logs. Les administrateurs habitués aux outils Unix peuvent ensuite combiner ce fichier avec des commandes comme tail, ou mieux, avec la surveillance en continu décrite dans un tutoriel dédié comme cet article sur la commande tailf. Sur une infra plus avancée, les logs partent parfois directement dans une stack centralisée type ELK ou Loki.
Exemple de log erreurs PHP et usage concret en debug
Clara a mis en place un fichier /var/log/php/app1-error.log pour un projet sensible. La configuration ressemble à ceci :
log_errors = On
error_log = /var/log/php/app1-error.log
display_errors = Off
L’équipe de dev utilise ensuite une simple commande pour suivre les erreurs en temps réel lors des tests de charge :
tail -f /var/log/php/app1-error.log
Ce genre de configuration évite que des messages internes apparaissent aux yeux de l’utilisateur final tout en offrant un suivi précis des incidents. Couplé à un monitoring applicatif, cela devient un réflexe aussi naturel que la surveillance d’un reverse proxy ou d’un firewall. Et si l’on a besoin de remonter un cran plus haut, les articles de prise en main Unix comme ce guide sur les commandes de base donnent un socle utile pour manipuler ces fichiers sereinement.
Créer un gestionnaire d’erreurs personnalisé pour structurer les messages
Dès que l’on veut garder la main sur le format des messages d’erreur, la fonction set_error_handler() devient un outil intéressant. Elle permet de rediriger toutes les erreurs non fatales vers une fonction maison, qui décide ensuite quoi faire : journalisation avancée, envoi de mail d’alerte, affichage d’un message simplifié, ou combinaison des trois. Ce modèle convient bien aux applications métier qui nécessitent un suivi précis de certains scénarios sans pour autant tout exposer en clair.
Un squelette de gestionnaire ressemble par exemple à ceci :
function appErrorHandler($errno, $errstr, $errfile, $errline) {
// Filtrage, formatage, envoi vers un log dédié
}
set_error_handler(‘appErrorHandler’);
Dans cette fonction, il est possible de construire un message enrichi avec date, identifiant de requête, utilisateur courant et contexte applicatif. Certains préfèrent y intégrer aussi des informations sur l’URL ou le payload de la requête, en veillant toutefois à ne jamais stocker de données sensibles en clair (mots de passe, numéros de carte, etc.). Un bon compromis consiste à anonymiser ou tronquer ces informations avant enregistrement.
Combiner gestionnaire d’erreurs, exceptions et logs
Pour couvrir l’ensemble des problèmes, il ne suffit pas de surveiller uniquement les erreurs classiques. Les exceptions non attrapées, par exemple, méritent elles aussi un traitement homogène. D’où l’intérêt de coupler set_error_handler() avec set_exception_handler() pour centraliser le comportement. On obtient alors une « porte d’entrée » unique pour la plupart des situations, qui peut ensuite déléguer vers plusieurs fichiers de log erreurs PHP en fonction de la criticité.
Un pattern courant consiste à :
- Convertir certains types d’erreurs en exceptions pour les manipuler plus facilement.
- Diriger les erreurs critiques vers un canal d’alerte (mail, Slack, outil de monitoring).
- Envoyer les avertissements et notices dans un log distinct pour ne pas noyer l’important.
Sur un projet qui commence à grossir, cette structuration fait gagner des heures lors des phases d’investigation. Au lieu de feuilleter un seul fichier gigantesque, l’équipe se concentre directement sur le bon canal selon le type d’incident rencontré. Cette approche vaut largement le temps investi au départ, un peu comme le fait de poser un schéma d’architecture avant d’empiler des machines virtuelles au hasard.
Outils et bonnes pratiques pour un debug PHP propre en dev et en production
Les paramètres de configuration PHP forment la base, mais la réalité des projets demande souvent un peu plus de confort. Sur les postes de développement, des extensions comme Xdebug restent utiles pour remonter des stack traces détaillées, profiler le code ou poser des points d’arrêt dans un IDE. Relié à un environnement comme PhpStorm ou VS Code, cela permet de suivre l’exécution ligne par ligne plutôt que de se contenter de var_dump éparpillés partout.
En production, on cherche plutôt à limiter les informations visibles tout en gardant un historique exploitable. Certaines équipes complètent les log erreurs PHP par des outils d’agrégation et de recherche, afin de repérer les tendances (erreurs répétitives, incidents après une mise en production, etc.). Ce genre d’outillage n’empêche pas de garder une discipline de base : désactiver systématiquement display_errors en production, vérifier régulièrement la taille des fichiers de log et automatiser leur rotation.
Liste ciblée de bonnes pratiques pour l’affichage des erreurs PHP
Pour garder un fil conducteur entre les différents environnements sans transformer le debug en casse-tête, quelques règles simples méritent d’être posées noir sur blanc :
- Toujours activer l’affichage erreur dans le navigateur sur les environnements de développement uniquement.
- Jamais n’activer display_errors en production, même pour « tester vite fait » un bug sur le serveur live.
- Documenter précisément où sont stockés les logs (chemins, rotation, accès) et qui a le droit de les consulter.
- Privilégier un gestionnaire d’erreurs et d’exceptions centralisé pour uniformiser le traitement.
- Mettre en place des pages d’erreur propres côté front, qui masquent les détails techniques tout en indiquant un identifiant d’incident aux utilisateurs.
Une fois ces règles intégrées au projet, la gestion des messages d’erreur devient un outil de pilotage plutôt qu’un symptôme gênant. On passe d’un mode réactif, où l’on subit chaque incident, à un mode plus structuré où chaque problème laisse une trace exploitable pour l’amélioration continue.
Comment activer rapidement l’affichage des erreurs PHP dans le navigateur sur un projet en développement ?
Pour un affichage immédiat des erreurs PHP dans le navigateur, ajoutez au début de votre script ou d’un fichier de configuration inclus : ini_set(‘display_errors’, 1); ini_set(‘display_startup_errors’, 1); error_reporting(E_ALL);. Utilisez ce bloc uniquement sur un environnement de développement et évitez absolument de le laisser en production pour ne pas exposer des informations sensibles.
Pourquoi mes messages d’erreur PHP n’apparaissent pas malgré display_errors à On ?
Plusieurs causes possibles : un autre fichier de configuration (php.ini global, .htaccess, vhost) peut forcer display_errors à Off, les erreurs sont peut-être redirigées uniquement vers un fichier de log via log_errors, ou bien l’erreur est fatale avant que le script n’atteigne l’appel à ini_set. Vérifiez en priorité la configuration chargée via phpinfo(), puis inspectez les fichiers de logs définis par error_log.
Comment configurer les logs d’erreurs PHP sur un serveur Linux de façon propre ?
Activez log_errors à On dans php.ini ou un fichier .ini dédié et pointez error_log vers un chemin géré par votre système de rotation de logs, par exemple /var/log/php/error.log. Assurez-vous que les droits sur le répertoire permettent à l’utilisateur du processus PHP d’écrire, puis utilisez un outil comme tail ou tailf pour suivre le fichier en temps réel. Intégrez ensuite ce fichier dans votre solution de supervision ou de collecte centralisée si vous en utilisez une.
Quelle différence entre error_reporting(E_ALL) et l’option par défaut de PHP ?
error_reporting(E_ALL) force PHP à signaler tous les niveaux d’erreur disponibles pour la version utilisée, y compris les notices et avertissements que la configuration par défaut peut choisir d’ignorer. En développement, cette granularité est intéressante pour corriger un maximum de problèmes en amont. En production, beaucoup d’équipes préfèrent limiter les niveaux remontés dans les logs aux erreurs et avertissements vraiment bloquants, afin de ne pas saturer les fichiers.
Faut-il utiliser un gestionnaire d’erreurs personnalisé dans un petit projet PHP ?
Sur un petit projet purement interne, un gestionnaire d’erreurs personnalisé n’est pas obligatoire, mais il apporte un vrai confort dès que plusieurs personnes interviennent ou que le projet commence à durer. Il permet de structurer les logs, de filtrer certains messages, et d’éviter que des erreurs peu importantes perturbent les utilisateurs. Même une implémentation simple, qui formate proprement les erreurs et les envoie dans un fichier dédié, peut faire gagner un temps non négligeable lors des futures investigations.
