Une erreur PHP qui se traduit par une page blanche ou un laconique « 500 Internal Server Error » peut stopper net une journée de travail. Tout se joue alors sur un détail de configuration PHP que personne n’a envie d’ouvrir à 22 h après une longue session de code. Pourtant, avec quelques réflexes sur display_errors, log_errors, le fichier php.ini et un minimum de discipline, l’activation affichage erreur peut devenir un outil confortable plutôt qu’un casse-tête. Le but n’est pas seulement de faire apparaître les messages d’erreur « par magie » dans le navigateur, mais de poser un cadre sain entre environnement de développement bavard et production silencieuse qui logue tout proprement côté serveur.
Sur un projet PHP moderne, les contextes se multiplient. Entre le laptop de dev, un conteneur de préproduction et un mutualisé un peu limité pour un client, l’affichage des erreurs doit s’adapter. Clara, dev full stack dans une petite agence web, jongle régulièrement avec ces trois mondes. En local, elle veut voir la moindre notice remonter en haut de la page. En staging, elle préfère que le debug PHP passe par un fichier de log. En production, elle veut uniquement des pages d’erreur propres pour l’utilisateur, tout en gardant un rapport d’erreur très détaillé dans des journaux consultables à tête reposée. C’est exactement ce jeu d’équilibriste que cet article décortique, en montrant comment brancher correctement l’affichage navigateur et la journalisation serveur.
Le fil rouge est simple : apprendre à piloter les messages d’erreur comme un outil de diagnostic, et non comme un bruit de fond stressant. Les réglages clés seront passés en revue, depuis le trio ini_set/display_errors/error_reporting au réglage global dans php.ini, en passant par les fichiers .htaccess, les directives de vhost Apache ou FPM, puis la mise en place de logs d’erreurs PHP structurés. On verra aussi comment un gestionnaire d’erreurs personnalisé et quelques bons réflexes inspirés d’autres sujets du quotidien des devs, comme la gestion d’un site e‑commerce ou d’un blog WordPress, peuvent rendre l’ensemble vraiment agréable à vivre.
- Activer l’affichage des erreurs PHP dans le navigateur passe par display_errors et error_reporting, idéalement limités aux environnements de développement.
- Configurer php.ini permet de fixer des règles globales, mais demande une séparation stricte entre dev, préprod et production.
- Loguer les erreurs PHP côté serveur avec log_errors et error_log évite de révéler des détails sensibles tout en gardant une trace complète.
- Adapter la configuration PHP selon le contexte (script, vhost, conteneur) simplifie la vie quand plusieurs projets partagent la même machine.
- Mettre en place un gestionnaire d’erreurs personnalisé donne un vrai contrôle sur le format, la sévérité et la destination des messages d’erreur.
Afficher les erreurs PHP dans le navigateur sans se tirer une balle dans le pied
Pour le quotidien du dev, le plus précieux reste souvent l’affichage direct des messages d’erreur dans le navigateur. Quand Clara travaille sur une nouvelle fonctionnalité, elle veut voir immédiatement où ça coince, sans avoir à ouvrir un log système. La méthode la plus simple consiste à injecter un bloc dédié en tout début d’exécution, par exemple dans un fichier bootstrap ou index central.
Le schéma classique repose sur trois lignes, qui forcent un debug PHP très bavard :
Exemple à placer en développement uniquement
<?php
ini_set(‘display_errors’, 1);
ini_set(‘display_startup_errors’, 1);
error_reporting(E_ALL);
?>
Ce trio a plusieurs effets concrets. La directive display_errors indique à PHP d’afficher les messages d’erreur à l’écran. display_startup_errors se concentre sur les problèmes au démarrage de PHP, souvent oubliés mais parfois responsables de gros blocages. Enfin, error_reporting(E_ALL) active la remontée de tous les niveaux d’erreur compatibles avec la version de PHP utilisée, depuis la notice un peu agaçante jusqu’à l’erreur fatale.
Ce réglage peut sembler bruyant, mais il a une vertu : faire ressortir tôt les incohérences de code, par exemple des variables non définies ou des usages de fonctionnalités dépréciées. Masquer ces signaux en phase de développement revient souvent à repousser un problème qui explosera plus tard, quand l’application sera déjà en production.
Pour rester propre, Clara place ce bloc dans un fichier de configuration spécifique, par exemple config.dev.php, qu’elle inclut uniquement lorsqu’une variable d’environnement signale que l’instance tourne en mode développement. Sur le serveur de production, ce fichier n’existe simplement pas, ce qui évite toute activation affichage erreur accidentelle devant les utilisateurs.
Autre détail à garder en tête : un appel à ini_set affecte uniquement le script en cours (et ce qu’il inclut), pas le serveur entier. C’est une bonne nouvelle pour les tests ciblés, mais cela veut dire qu’une erreur de syntaxe avant ce bloc, ou un problème de démarrage au niveau du moteur PHP, ne passera pas par ces réglages. Pour ces cas-là, il faudra aller regarder du côté du php.ini, des logs du serveur web ou d’un outil de supervision.
Une astuce utile consiste à regrouper ces lignes dans une petite fonction réutilisable, que l’on appelle au tout début des scripts de développement :
<?php
function dev_debug_on() {
ini_set(‘display_errors’, ‘1’);
ini_set(‘display_startup_errors’, ‘1’);
error_reporting(E_ALL);
}
dev_debug_on();
?>
Ce genre de wrapper facilite le jour où l’on souhaite ajuster le comportement, par exemple pour filtrer un type précis de notices. Cela évite aussi les copier‑coller sauvages de lignes isolées au milieu des scripts, qui finissent souvent oubliées au moment du déploiement.
Pourquoi éviter display_errors en production même pour un « petit » site
La tentation est réelle : laisser display_errors à On sur un site jugé peu sensible, « juste pour gagner du temps » quand un bug remonte côté client. Mauvaise idée. Un message d’erreur PHP détaillé peut révéler le chemin physique des fichiers, la structure des classes, des requêtes SQL, parfois même un bout de configuration contenant des secrets si le code est mal protégé. Autant de cadeaux offerts aux scripts d’attaque automatisés.
En production, la règle simple tient en une ligne : display_errors doit être désactivé, log_errors activé. On bascule alors vers un modèle où l’utilisateur voit une page soignée, éventuellement avec un identifiant d’incident, tandis que l’équipe technique consulte les journaux d’erreurs pour comprendre ce qui s’est passé. Les frameworks modernes poussent déjà dans ce sens, mais sur un projet PHP plus « artisanal », ce choix revient au développeur.
En résumé, l’affichage des erreurs dans le navigateur est un outil de développement, pas un mode de fonctionnement permanent. La bascule vers une approche centrée sur les logs prépare directement la suite : la configuration globale dans php.ini.
Activer l’affichage des messages d’erreur PHP via php.ini et fichiers de configuration
Lorsque plusieurs projets partagent la même machine ou le même conteneur, multiplier les ini_set dans chaque script devient vite pénible. C’est là que la configuration globale prend tout son sens. Le fichier php.ini sert de colonne vertébrale : ce que tu y définis s’applique par défaut à tous les scripts servies par cette instance de PHP, sauf override local.
Sur un serveur de développement partagé par une équipe, Clara préfère centraliser les réglages de debug. Par exemple, sur une instance dédiée à la recette, elle adapte la configuration de base :
display_errors = On
display_startup_errors = On
error_reporting = E_ALL
log_errors = On
error_log = /var/log/php/dev-error.log
Après redémarrage d’Apache ou de PHP-FPM, tous les scripts profitent de cet affichage généreux des messages d’erreur. Cette approche évite le fameux « chez moi ça marche » quand deux devs n’ont pas les mêmes réglages locaux. Le revers de la médaille est évident : si cette instance commence à accueillir un site exposé au public, ces réglages deviennent un facteur de risque. D’où l’intérêt de séparer clairement les profils de PHP utilisés par environnement (dev, staging, prod).
Sur des hébergements mutualisés, l’accès direct à php.ini est parfois interdit. À la place, l’hébergeur propose souvent un mini panneau de configuration, ou accepte certaines directives via un fichier .htaccess. Typiquement, on rencontre ce genre de bloc :
php_value display_errors 1
php_value display_startup_errors 1
php_value error_reporting E_ALL
Ce fichier s’applique alors au dossier courant et à ses sous‑répertoires, ce qui permet à un seul site d’activer l’affichage des erreurs sans impacter les autres. Certains prestataires désactivent toutefois cette possibilité pour des raisons de sécurité, et ignorent les directives PHP dans .htaccess. Dans ce cas, il faut se rabattre sur les options offertes par leur interface ou sur une configuration spécifique fournie par le support.
Sur un couple Nginx/PHP‑FPM, la logique change un peu. Pas de .htaccess, et souvent plusieurs « pools » FPM, chacun avec son propre fichier d’override. Le dossier /etc/php/…/fpm/conf.d/ peut contenir des fichiers .ini dédiés à un projet ou à un environnement. Clara y dépose par exemple un fichier 99-dev.ini pour les conteneurs de développement :
display_errors = On
display_startup_errors = On
error_reporting = E_ALL
Cette approche par profil colle bien aux architectures qui séparent déjà les flux HTTP, comme on le ferait pour distinguer un front prestashop d’une API back‑office. D’ailleurs, la comparaison entre plateformes, abordée dans un article comme Prestashop vs Shopify, montre à quel point la gestion des environnements reste un sujet transversal, que l’on parle d’e‑commerce ou de simple site vitrine.
Comparer les niveaux de configuration pour l’affichage des erreurs PHP
Pour s’y retrouver entre tous ces points de réglage, un tableau de synthèse aide à visualiser la portée réelle de chaque option. Cela évite le classique « j’ai mis display_errors à On, mais rien ne s’affiche », alors que la valeur est écrasée ailleurs.
| Niveau de configuration | Portée | Forces | Points de vigilance |
|---|---|---|---|
| php.ini global | Toutes les applications sur l’instance PHP | Configuration unifiée, pratique pour dev et recette partagés | Un mauvais réglage de display_errors peut exposer plusieurs sites en même temps |
| .htaccess / vhost Apache | Un seul site ou VirtualHost | Contrôle par projet, adapté au mutualisé | Directives parfois bloquées par l’hébergeur, conflits possibles avec php.ini |
| conf.d / pool FPM | Profil PHP spécifique (dev, prod, CLI) | Permet de différencier très finement les environnements | Nécessite de bien documenter quel profil sert quel site |
| ini_set dans le code | Script et includes associés | Idéal pour un debug ponctuel ou un environnement local isolé | Facile à oublier en production, dépend de l’ordre d’exécution |
Une règle pragmatique ressort souvent sur le terrain : bloquer globalement l’affichage dans php.ini en production (display_errors = Off), n’ouvrir que ce qui est nécessaire au niveau des profils de dev, et réserver ini_set à des cas très localisés ou expérimentaux. Tout ce qui sort de ce cadre doit être documenté comme une exception, au même titre qu’un port réseau ouvert en urgence.
Configurer log_errors et error_log pour des fichiers d’erreurs PHP vraiment utiles
Une fois l’affichage des erreurs navigateur cantonné au développement, la vraie star en production devient la journalisation serveur. L’objectif est clair : faire vivre les messages d’erreur dans des fichiers lisibles, centralisables et, idéalement, intégrés à un outil de supervision. C’est exactement ce que permettent les directives log_errors et error_log.
Clara gère par exemple un intranet pour une PME, hébergé sur un serveur Linux classique. Sur l’instance PHP utilisée par la production, les réglages ressemblent à ceci :
display_errors = Off
log_errors = On
error_log = /var/log/php/intranet-error.log
error_reporting = E_ALL & ~E_NOTICE & ~E_DEPRECATED
Les erreurs ne s’affichent plus dans le navigateur, mais chaque incident significatif est noté dans un fichier dédié. Le filtrage du rapport d’erreur via error_reporting limite le bruit des notices et des fonctions dépréciées, tout en gardant les vrais problèmes. Le fichier /var/log/php est intégré à la rotation de logs du système, ce qui évite de remplir le disque dur avec des fichiers gigantesques oubliés pendant des années.
Pendant une phase de test de charge, l’équipe ouvre un terminal et suit les erreurs en temps réel :
tail -f /var/log/php/intranet-error.log
À chaque requête problématique, une nouvelle ligne apparaît. Ce flux temps réel permet d’aligner immédiatement un incident client avec un message dans le log. Quand la charge retombe, les devs reprennent le fichier au calme pour analyser les motifs récurrents, par exemple un endpoint d’API qui renvoie régulièrement des warnings.
La même logique se transpose très bien à des setups plus ambitieux, avec des stacks de logs centralisées. Que l’on pousse les erreurs PHP dans un ELK, un Loki ou un autre agrégateur, le socle reste le même : log_errors à On, error_log pointé vers un fichier ou un pipe adapté. Le reste n’est qu’une question d’outillage.
Combiner logs PHP et logs applicatifs pour un diagnostic plus fin
Un piège courant consiste à se reposer uniquement sur les logs PHP bruts. Or une bonne partie des soucis métier ne sont pas des erreurs au sens de PHP, mais des cas fonctionnels. Dans un générateur de nombres aléatoires maison, par exemple, un bug logique peut entraîner des distributions bizarres sans provoquer le moindre warning. C’est là qu’un journal applicatif, séparé des logs de bas niveau, devient précieux.
Sur un projet qui s’appuie par exemple sur un outil externe comme le générateur de nombres aléatoires décrit ailleurs, Clara ajoute des appels à error_log pour tracer certains scénarios métier. Couplé à log_errors, PHP envoie alors ces messages dans le même fichier que les erreurs techniques, avec un préfixe spécifique, par exemple [APP]. Le mélange des deux couches fournit un récit beaucoup plus riche au moment d’analyser un incident.
On en revient toujours à la même idée : faire des logs un outil de navigation dans l’historique de l’application, plutôt qu’une simple poubelle de warnings obscurs. Bien paramétrés, les journaux d’erreurs permettent de recoller les morceaux entre un bug signalé par un utilisateur et un événement précis côté serveur.
Gestionnaire d’erreurs personnalisé, exceptions et politique de rapport d’erreur
Quand un projet PHP grandit, s’appuyer seulement sur display_errors, log_errors et error_log finit par montrer ses limites. Les messages restent bruts, parfois difficiles à corréler, et la distinction entre erreur critique et simple notice devient floue. C’est là que les fonctions set_error_handler et set_exception_handler entrent en scène.
L’idée est simple : déclarer une fonction maison qui recevra toutes les erreurs ou exceptions non gérées, puis décider de la façon de les formater, de les classer et de les envoyer vers les bons canaux. Un squelette typique pourrait ressembler à ceci :
<?php
function appErrorHandler($errno, $errstr, $errfile, $errline) {
$message = ‘[‘.date(‘Y-m-d H:i:s’).’] ‘;
$message .= « Erreur {$errno} dans {$errfile} ligne {$errline} : {$errstr} »;
error_log($message);
}
set_error_handler(‘appErrorHandler’);
?>
Avec ce genre de gestionnaire, chaque événement passe par un format commun. Il devient possible d’ajouter des métadonnées, par exemple un identifiant de requête, un utilisateur connecté, voire l’URL concernée. En production, Clara filtre parfois certains types d’erreurs pour les envoyer sur des canaux distincts : un fichier pour les notices, un autre pour les erreurs critiques susceptibles de déclencher une alerte.
Du côté des exceptions, la logique est proche. Un set_exception_handler capte tout ce qui n’a pas été attrapé par un bloc try/catch local. Le gestionnaire unique peut alors consigner l’exception, éventuellement afficher une page d’erreur propre côté front, et décider de la stratégie de notification (mail, Slack, outil de monitoring).
Ajuster error_reporting pour un rapport d’erreur adapté au contexte
La variable error_reporting joue un rôle de filtre global sur ce qui remonte dans le système de gestion d’erreurs. En développement, viser E_ALL reste pertinent. Dans certains cas, l’usage de la valeur -1 garantit même que tous les futurs niveaux d’erreur introduits par PHP seront inclus. Ce réglage maximal facilite la chasse aux mauvaises habitudes, comme les variables non initialisées.
En production, la donne change. Un serveur qui reçoit des millions de requêtes par jour ne peut pas se permettre de loguer toutes les notices. Le risque de saturer les disques et de rendre les fichiers illisibles dépasse largement le bénéfice de ces détails. L’équilibre le plus courant ressemble à ceci :
error_reporting = E_ALL & ~E_NOTICE & ~E_STRICT & ~E_DEPRECATED
Ce compromis garde les erreurs et avertissements sérieux, tout en évitant le bruit des recommandations de style ou des fonctionnalités appelées à disparaître à long terme. Une équipe qui mène des migrations de version régulières pourra ponctuellement réactiver E_DEPRECATED sur un environnement de test, histoire de préparer en amont un passage à une nouvelle version majeure de PHP.
Cette granularité du rapport d’erreur donne une vraie marge de manœuvre pour adapter la configuration PHP selon la maturité du projet. Un side‑project interne tolérera un peu plus de bruit dans les logs. Un gros site marchand versionné à la seconde près demandera au contraire une politique très réfléchie, au même titre que les arbitrages faits sur la stack technique, la gestion du cache ou les solutions de paiement.
Bonnes pratiques pour aligner affichage des erreurs et sécurité sur l’ensemble du projet
Au‑delà des réglages bruts, ce qui fait la différence sur un projet, c’est la cohérence entre tous les environnements. Un site vitrine géré à la va‑vite peut survivre avec un php.ini bricolé sur le serveur live. Une application métier critique, ou même un blog à fort trafic, ne peut pas se permettre ce genre d’improvisation. Les débats autour des conflits d’usage entre outils comme WordPress et certains créateurs de contenu, décrits dans un article tel que conflit WordPress et blogueurs, montrent à quel point la couche technique influence directement la vie des utilisateurs.
Pour rendre la gestion des erreurs PHP vivable au quotidien, Clara formalise quelques règles simples avec son équipe. Ces règles sont écrites dans la documentation du projet, au même titre que la procédure de déploiement ou les conventions de nommage. Voici une synthèse de ces principes.
- Dev local : display_errors = On, error_reporting(E_ALL), log_errors activé, logs stockés dans le projet (par exemple ./var/log/php-error.log).
- Environnement de test / préprod : display_errors désactivé pour les testeurs externes, mais accessible via un flag spécifique pour l’équipe technique, log_errors à On avec rotation de fichiers.
- Production : display_errors = Off de manière non négociable, log_errors = On, séparation des logs applicatifs et systèmes, accès restreint aux fichiers de logs.
- Gestionnaire d’erreurs central pour uniformiser le format et la sévérité des messages d’erreur, couplé à set_exception_handler.
- Revue régulière des logs pour repérer les motifs récurrents, et non seulement pour réagir aux incidents les plus bruyants.
Ces quelques lignes, appliquées avec constance, transforment la façon dont l’équipe perçoit les erreurs. Elles deviennent des signaux normaux à traiter, pas des catastrophes incompréhensibles. L’affichage des erreurs dans le navigateur reste un outil de développement puissant, mais il s’inscrit enfin dans un cadre global où la priorité reste la stabilité en production.
Comment activer rapidement l’affichage des erreurs PHP dans le navigateur sur un projet en développement ?
Pour un affichage immédiat, ajoute au tout début de ton script ou d’un fichier de configuration inclus ces lignes : ini_set(‘display_errors’, 1); ini_set(‘display_startup_errors’, 1); error_reporting(E_ALL);. Elles forcent PHP à montrer tous les messages d’erreur à l’écran. Garde ce bloc uniquement en environnement de développement et retire-le avant tout déploiement en production pour éviter d’exposer des informations sensibles.
Pourquoi mes erreurs PHP ne s’affichent pas malgré display_errors à On ?
Plusieurs causes existent : un autre fichier de configuration (php.ini global, .htaccess, vhost) peut forcer display_errors à Off, l’option log_errors peut envoyer les messages uniquement dans un fichier de log, ou bien l’erreur survient avant que le script atteigne l’appel à ini_set. Commence par vérifier la configuration active avec phpinfo(), puis regarde les chemins configurés dans error_log pour voir si les messages sont enregistrés ailleurs.
Comment configurer correctement log_errors et error_log sur un serveur Linux ?
Active log_errors à On dans php.ini ou un fichier .ini dédié, puis choisis un chemin adapté pour error_log, par exemple /var/log/php/error.log. Assure-toi que l’utilisateur qui exécute PHP a le droit d’écrire dans ce répertoire. Intègre ensuite ce fichier à la rotation de logs du système, et utilise des commandes comme tail -f pour suivre les erreurs en temps réel. Si tu disposes d’une stack de logs centralisée, ajoute ce fichier à la collecte pour le retrouver dans ton outil de supervision.
Quelle différence entre error_reporting(E_ALL) et la configuration par défaut de PHP ?
error_reporting(E_ALL) demande à PHP de rapporter tous les niveaux d’erreur pris en charge par la version installée, y compris les notices et avertissements souvent ignorés par la configuration par défaut. Cela permet de repérer plus tôt les mauvaises pratiques et les comportements ambigus. Sur un serveur de production soumis à forte charge, beaucoup d’équipes préfèrent ajuster la valeur pour exclure les notices et les messages liés aux fonctionnalités dépréciées, afin de ne pas saturer les fichiers de log.
Un gestionnaire d’erreurs personnalisé est-il utile pour un petit projet PHP ?
Même sur un petit projet, un gestionnaire d’erreurs personnalisé apporte du confort dès qu’il s’agit de comprendre ce qui s’est passé plusieurs jours après un incident. Il permet de formater les messages avec une date, un contexte, voire un identifiant de requête, et de les envoyer vers un fichier dédié. Cela simplifie beaucoup les investigations, surtout si plusieurs personnes interviennent sur le code ou si le projet dure plusieurs mois.
