error_log()

Journalisation des erreurs PHP avec la fonction error_log

Afficher les erreurs à l'écran avec echo ou var_dump() est pratique lors du développement d'une fonctionnalité, mais c'est la mauvaise approche en production : la sortie est visible par les visiteurs, se perd lors des appels AJAX, et disparaît dès la fin de la requête. La fonction intégrée error_log() résout ce problème en envoyant un message vers une destination durable — un fichier journal, un e-mail ou le journal du système d'exploitation — afin que vous puissiez le consulter ultérieurement.

Ce guide explique ce que fait error_log(), parcourt chaque paramètre avec des exemples exécutables, et couvre les pièges (sauts de ligne manquants, la directive ini error_log, ce qu'il ne faut pas journaliser) qui surprennent les développeurs dans de vrais projets.

Ce que fait la fonction error_log()

error_log() écrit un seul message vers une destination de votre choix. Elle ne déclenche pas le mécanisme d'erreur de PHP, ne modifie pas le code de sortie et n'interrompt pas le script — elle ne fait qu'enregistrer du texte. La valeur de retour est un bool : true en cas de succès, false si le message n'a pas pu être écrit (par exemple, si le fichier journal n'est pas accessible en écriture).

Parce qu'elle se résume à « ajouter cette chaîne quelque part », error_log() est le moyen le plus simple de laisser des traces dans du code qui s'exécute sans développeur pour le surveiller — tâches cron, workers de file d'attente, webhooks, et toute requête en production.

Signature de la fonction

error_log(
    string $message,
    int $message_type = 0,
    ?string $destination = null,
    ?string $additional_headers = null
): bool

Par défaut : journaliser vers la destination configurée de PHP

L'appel le plus courant ne passe que le message et laisse PHP l'acheminer là où le serveur est configuré pour envoyer les erreurs (la directive ini error_log, ou le journal SAPI/système si celle-ci n'est pas définie) :

<?php

error_log("Payment gateway returned an unexpected status code");

C'est exactement là où vont déjà les avertissements et les notices non capturés, de sorte que vos messages manuels se retrouvent aux côtés des propres erreurs de PHP. Pour voir la cible actuelle à l'exécution, lisez la valeur ini :

<?php

echo ini_get('error_log') ?: '(SAPI / system default)';

Journalisation dans un fichier spécifique (type 3)

Le type 3 ajoute le message à la fin d'un fichier que vous nommez dans $destination. C'est la méthode de référence pour les journaux spécifiques à une application :

<?php

$message = "Error: Unable to connect to the database";
error_log($message, 3, "/var/log/php-errors.log");

Contrairement au type 0, le type 3 écrit le message tel quel — sans horodatage, sans niveau de sévérité, et surtout sans saut de ligne en fin. Si vous oubliez ce saut de ligne, tous les appels se retrouvent concaténés sur une seule ligne :

<?php

$log = sys_get_temp_dir() . "/app.log";
error_log("first", 3, $log);
error_log("second", 3, $log);
echo file_get_contents($log); // firstsecond

Ajoutez PHP_EOL vous-même (et généralement un horodatage) pour que chaque entrée soit une ligne lisible :

<?php

$log = sys_get_temp_dir() . "/app.log";
$line = date('[Y-m-d H:i:s] ') . "Cache miss for user 42" . PHP_EOL;
error_log($line, 3, $log);

echo file_get_contents($log);
// [2026-06-21 10:00:00] Cache miss for user 42

Tous les types de messages

Le type 2 (envoi via un socket TCP) existait dans les anciennes versions de PHP et a été supprimé dans PHP 8 ; n'en dépendez pas.

Envoi d'erreurs critiques par e-mail (type 1)

Pour les échecs rares et très graves, vous pouvez demander à PHP de vous envoyer un e-mail. À utiliser avec parcimonie — une erreur bruyante qui se déclenche à chaque requête peut inonder une boîte de réception :

<?php

error_log(
    "FATAL: order processor crashed",
    1,
    "[email protected]",
    "From: [email protected]\r\n"
);

En production, une bibliothèque de journalisation qui regroupe et limite les alertes est plus adaptée qu'un e-mail à chaque appel.

Un modèle réaliste de capture et journalisation

Dans le code applicatif, vous journalisez généralement à l'intérieur d'un bloc catch, vous enregistrez suffisamment de contexte pour reproduire le problème, puis vous affichez un message générique à l'utilisateur :

<?php

function chargeCustomer(int $cents): bool
{
    if ($cents <= 0) {
        throw new InvalidArgumentException("Amount must be positive, got $cents");
    }
    // ... real charge logic ...
    return true;
}

try {
    chargeCustomer(-5);
} catch (Throwable $e) {
    error_log(sprintf(
        "[%s] %s in %s:%d",
        date('Y-m-d H:i:s'),
        $e->getMessage(),
        $e->getFile(),
        $e->getLine()
    ));
    echo "Sorry, we couldn't process your payment.";
}

Le message détaillé va dans le journal ; le visiteur ne voit que la ligne conviviale. Cette séparation est tout l'intérêt de error_log().

Pièges courants

• Pas de saut de ligne avec le type 3. Ajoutez PHP_EOL vous-même, sinon vos entrées sont concaténées.
• La directive ini error_log définit la destination par défaut. Lorsque vous omettez $message_type/$destination, le message va là où pointe ini_get('error_log'). Sur une installation CLI vierge, il peut s'agir de stderr ; sur un serveur web, d'un fichier spécifique.
• Le fichier doit être accessible en écriture par le processus PHP. Un retour false signifie souvent un problème de permissions sur le répertoire ou le fichier.
• display_errors et error_log sont indépendants. Désactiver l'affichage des erreurs à l'écran n'arrête pas la journalisation, et vice versa — contrôlez-les séparément.
• Ne jamais journaliser des secrets. Les mots de passe, les clés API, les numéros de carte de crédit complets et les tokens de session ne doivent jamais atteindre un fichier journal. Expurgez-les avant d'appeler error_log().

Fonctions associées

• set_error_handler() — acheminez les avertissements et notices propres à PHP à travers votre code afin de pouvoir appeler error_log() de manière cohérente.
• set_exception_handler() — capturez et journalisez les exceptions non attrapées autrement en un seul endroit.
• trigger_error() — déclenchez une erreur de niveau utilisateur que le gestionnaire d'erreurs (et donc la journalisation) prendra en charge.
• error_reporting() — choisissez quels niveaux d'erreur sont signalés en premier lieu.
• syslog() — envoyez des messages directement au journal système avec un niveau de sévérité.

Conclusion

error_log() est le moyen durable le plus simple d'enregistrer ce qui s'est mal passé dans du code qu'aucun développeur ne surveille. Utilisez le type 3 avec un horodatage et PHP_EOL pour les fichiers journaux applicatifs, revenez à la destination par défaut pour vous placer à côté des propres erreurs de PHP, et réservez l'e-mail (type 1) aux événements véritablement critiques. Associez-le à set_error_handler() et set_exception_handler() pour tout capturer en un seul endroit — et n'écrivez jamais de secrets dans un journal.

Exercice