error_reporting()

Introduction

Ce chapitre explique comment PHP signale les erreurs : la fonction error_reporting() qui contrôle quelles erreurs PHP génère, les directives display_errors et log_errors qui contrôlent où ces erreurs sont envoyées, ainsi que les fonctions auxiliaires permettant de les gérer et de les journaliser. À la fin, vous saurez comment configurer le rapport d'erreurs différemment selon l'environnement de développement ou de production, et pourquoi une mauvaise configuration est l'une des erreurs de sécurité et de débogage les plus courantes en PHP.

Pourquoi le rapport d'erreurs est important

PHP s'exécute comme un langage dynamique et permissif : de nombreuses erreurs qui empêcheraient la compilation d'un autre langage se manifestent à l'exécution sous forme d'avertissements, de notices ou de messages de dépréciation. Si vous les supprimez, un comportement défaillant peut passer silencieusement en production. Si vous les affichez aux utilisateurs finaux, vous risquez d'exposer des chemins de fichiers, du SQL et des traces de pile à des attaquants.

Un bon rapport d'erreurs établit le bon équilibre pour chaque environnement :

• En développement — tout afficher, de façon visible, pour détecter les bogues au fur et à mesure que vous les écrivez.
• En production — ne rien afficher à l'utilisateur, mais tout journaliser dans un fichier pour une analyse ultérieure.

Niveaux d'erreurs et constantes

Les erreurs PHP sont classées par niveau. Chaque niveau est une constante prédéfinie, et vous les combinez à l'aide d'opérateurs bit à bit. Les niveaux les plus courants :

Comme ce sont des drapeaux binaires, vous les combinez avec | (inclure), & (masque) et ~ (négation) :

// All errors EXCEPT notices and deprecation messages
error_reporting(E_ALL & ~E_NOTICE & ~E_DEPRECATED);

// Only fatal errors and warnings
error_reporting(E_ERROR | E_WARNING);

Note de version : Depuis PHP 8.0, le niveau error_reporting par défaut est E_ALL. E_STRICT a été déprécié en 8.0 et supprimé en 8.4, et ses notices sont désormais incluses dans E_ALL, vous n'avez donc plus besoin de l'ajouter séparément.

Signalement et affichage : deux réglages distincts

Une source fréquente de confusion est que deux commutateurs indépendants déterminent si vous voyez réellement une erreur :

1. error_reporting() — détermine les niveaux que PHP génère.
2. display_errors — détermine si les erreurs générées sont affichées dans la sortie.

Vous devez activer les deux pour voir une erreur à l'écran. L'exemple ci-dessous génère une notice de niveau E_ALL et l'affiche car les deux commutateurs sont activés :

<?php
error_reporting(E_ALL);
ini_set('display_errors', '1');

echo $undefined;   // Warning: Undefined variable $undefined

Si display_errors était désactivé, la même notice serait toujours générée (et pourrait être journalisée), mais rien n'apparaîtrait dans la sortie de la page.

Les fonctions principales de rapport d'erreurs

error_reporting()

Définit les niveaux d'erreurs signalés à l'exécution et retourne le niveau précédent. Appelez-la sans argument pour lire le réglage actuel.

<?php
$old = error_reporting(E_ALL & ~E_NOTICE);
echo "Now reporting all errors except notices.\n";
echo "Previous level was: " . $old . "\n";

ini_set()

Remplace une directive php.ini pour la durée du script en cours. C'est l'équivalent à l'exécution de la modification de php.ini, et c'est ainsi que vous basculez display_errors, display_startup_errors et log_errors depuis le code.

<?php
// Development setup: show everything on screen
ini_set('display_errors', '1');
ini_set('display_startup_errors', '1');
error_reporting(E_ALL);

Remarque : display_errors ne peut pas intercepter les erreurs fatales d'analyse syntaxique dans le même fichier, car le fichier entier échoue à la compilation avant l'exécution de ini_set(). Pour ces cas, définissez la directive directement dans php.ini.

set_error_handler()

Enregistre un callback qui s'exécute chaque fois qu'une erreur (non fatale) est déclenchée, vous permettant de remplacer le comportement par défaut de PHP — par exemple pour convertir des avertissements en exceptions ou les formater en JSON pour une API. Le callback reçoit le niveau d'erreur, le message, le fichier et la ligne.

<?php
set_error_handler(function (int $errno, string $errstr, string $errfile, int $errline): bool {
    echo "[$errno] $errstr in " . basename($errfile) . " on line $errline\n";
    return true; // true = we handled it; PHP's internal handler is skipped
});

echo $undefined; // routed to our handler instead of the default message

Consultez set_error_handler() pour la signature complète et pour savoir comment restaurer le gestionnaire précédent.

error_log() et trigger_error()

• error_log() envoie un message au journal configuré de PHP, à un fichier spécifique ou à une adresse e-mail — jamais dans la sortie de la page. C'est la méthode sûre pour la production afin d'enregistrer les problèmes.
• trigger_error() déclenche une erreur que vous définissez (niveaux E_USER_*), qui transite ensuite par le même pipeline error_reporting/gestionnaire que les erreurs intégrées.

<?php
// Append a message to a specific log file (message type 3)
error_log("Payment gateway timed out", 3, "/var/log/php_errors.log");

// Raise a user-level warning that your handler / log can pick up
trigger_error("Cache miss for product 42", E_USER_WARNING);

En savoir plus dans error_log() et trigger_error().

Configuration recommandée par environnement

Plutôt que de disperser les paramètres, placez-les en haut de votre fichier d'amorçage.

<?php
// --- Development ---
error_reporting(E_ALL);
ini_set('display_errors', '1');
ini_set('display_startup_errors', '1');

<?php
// --- Production ---
error_reporting(E_ALL);          // still GENERATE everything...
ini_set('display_errors', '0');  // ...but never show it to users...
ini_set('log_errors', '1');      // ...log it instead.
ini_set('error_log', '/var/log/php_errors.log');

Le bloc de production conserve une visibilité complète via les journaux tout en n'exposant rien aux visiteurs — la configuration que vous voulez presque toujours sur un serveur en production.

Bonnes pratiques

• Ne jamais exécuter la production avec display_errors activé. Les chemins et traces de pile exposés constituent un risque de divulgation d'informations.
• Signaler au niveau E_ALL partout. Le signalement et l'affichage sont distincts ; supprimer des niveaux ne fait que masquer des bogues.
• Évitez l'opérateur de suppression d'erreurs @. Il masque les erreurs au site d'appel et rend le débogage beaucoup plus difficile ; gérez explicitement la condition à la place.
• Interceptez ce que vous pouvez sous forme d'exceptions. Pour les échecs récupérables, préférez try/catch aux gestionnaires d'erreurs. Voir PHP Exceptions.
• Utilisez une bibliothèque de journalisation dans les grandes applications. Des outils comme Monolog vous offrent des niveaux de journalisation, la rotation et plusieurs destinations en plus de error_log().

Conclusion

Le rapport d'erreurs en PHP se résume à trois couches : choisir les niveaux avec error_reporting(), choisir la destination avec display_errors / log_errors, et éventuellement personnaliser la gestion avec set_error_handler() et trigger_error(). Configurez-les délibérément — verbeux à l'écran pendant le développement, silencieux mais journalisé en production — et vous obtenez un débogage rapide sans exposer votre application aux utilisateurs ni aux attaquants.

Lecture connexe : PHP Error handling · error_get_last() · try…catch.

Exercice pratique