Formation PUB010 : PHP, 2022 Déboguer un programme PHP

14.13 Fonction pour écrire dans un fichier journal (log file) : log_debug()


La majorité des langages de programmation offrent des fonctionnalités pour écrire dans un fichier journal (log file). On appelle parfois ce type de fichier journal des erreurs.

Le fichier journal peut contenir des messages d'erreur, des messages d'avertissement, des messages d'information et même des messages de débogage.

▼Publicité Le texte se poursuit plus bas

Où placer le fichier journal ?

Afin d'éviter de créer un trou de sécurité, le fichier journal ne doit pas être placé sous le dossier racine du site Web.

En effet, tout ce qui est sous ce dossier peut être lu à partir d'un navigateur, à moins d'ajouter des configurations spécifiques pour le serveur HTTP.

Un emplacement plus sécuritaire serait .../www/log.

Emplacement dossier log

Retrouver le chemin par programmation

Il faut éviter d'écrire en dur le chemin physique du site Web sinon, ce chemin sera invalide lors de la mise en ligne.

Pour y arriver, on travaillera avec :

  • La constante __FILE__ qui permet de retrouver le chemin complet du fichier dans lequel l'instruction est placée.
  • La fonction dirname() qui permet de retrouver le chemin complet d'un fichier parent.

En combinant les deux, on pourra retrouver le chemin du dossier racine du serveur HTTP.

L'instruction sera différente selon l'endroit où elle est écrite. En effet, le second paramètre de dirname() indique le nombre de niveaux à remonter dans la hiérarchie de fichiers. La valeur 1 représente le dossier courant, la valeur 2 permet de remonter d'un niveau, etc.

  • Si on est dans index.php, la valeur 2 permettra de retrouver la racine du serveur HTTP.
  • Si on est dans include/configuration.inc, la valeur 3 permettra de retrouver la racine du serveur HTTP.

Par exemple, pour retrouver la racine du serveur alors qu'on travaille dans include/configuration.inc :

Fichier monsite/include/configuration.inc (PHP)

$dossierRacineServeur = dirname(__FILE__, 3);

Nom du fichier journal

Il est d'usage de donner au fichier journal un nom qui représente l'application Web, par exemple monsite.log.

Le nom et le chemin du fichier journal devaient être définis dans une constante. Ceci permet de spécifier l'information à un seul endroit.

Notez l'utilisation de la constante DIRECTORY_SEPARATOR qui assurera que le chemin utilise une barre oblique inverse (\) sous Windows et une barre oblique (/) sous Mac ou Linux.

Fichier monsite/include/configuration.inc (PHP)

define('DEBUG_LOG_FILE', $dossierRacineServeur . DIRECTORY_SEPARATOR . 'log' . DIRECTORY_SEPARATOR . 'monsite.log');

Notez que PHP se chargera de créer le fichier journal mais il ne peut pas créer de dossier.

Pour que l'écriture puisse être effectuée, le dossier log doit exister et l'usager utilisé par le serveur HTTP doit détenir les droits requis pour l'écriture.

L'usager utilisé par le serveur HTTP dépend du serveur.

Par exemple :

  • sous Devilbox : devilbox
  • Sous AMPPS : www-data
  • Sous XAMPP : daemon
  • Sous Caddy : www-data

Enregistrer une information dans le fichier journal personnalisé

La fonction error_log() offre la possibilité de travailler dans un fichier journal personnalisé.

Il faut alors préciser en paramètre la valeur 3 pour indiquer que le message sera ajouté dans un fichier personnalisé. On précisera ensuite le chemin et le nom du fichier.

PHP

error_log("Mon premier message dans le fichier journal personnalisé!", 3, DEBUG_LOG_FILE);

Notez qu'il ne doit pas y avoir d'apostrophes ni de guillemets alentour du nom de la constante DEBUG_LOG_FILE.

Fonction log_debug()

La fonction log_debug(), qui peut aussi être appelée ou logDebug(), permet de loguer soit une chaîne de caractères, soit les détails d'un tableau ou d'un objet. Elle aura un comportement très semblable à la fonction echo_debug() (ou echoDebug()).

Le code de cette fonction va comme suit :

PHP

/**
 * Enregistre la date suivie d'une information de débogage dans le fichier journal (log) lorsque DEVEL est à true.
 * @author Christiane Lagacé <christiane.lagace@hotmail.com>
 *
 * Par défaut, le fichier journal est celui spécifié dans httpd.conf.
 * Peut être modifié à l'aide de la constante DEBUG_LOG_FILE.
 *     ex : $dossierRacineServeur = dirname(__FILE__, 3);
 *          define('DEBUG_LOG_FILE', $dossierRacineServeur . DIRECTORY_SEPARATOR . 'log' . DIRECTORY_SEPARATOR . 'mon-application.log');
 *
 * Utilisation : log_debug($_POST);
 *
 * @param String $message Information à inscrire dans le journal.
 */
function log_debug($message) {

    if (defined('DEVEL') && DEVEL === true) {
        if (is_array($message) || is_object($message)) {
            $message = print_r($message, true);
        }

        if (defined('DEBUG_LOG_FILE')) {
            error_log(date("F j, Y, g:i a") . " - Message de débogage: $message" . PHP_EOL, 3, DEBUG_LOG_FILE);
        }
        else {
            error_log(date("F j, Y, g:i a") . " - Message de débogage: $message" . PHP_EOL);
        }
    }
}

Remarque : différents caractères peuvent être utilisés pour effectuer un saut de ligne dans un fichier texte, selon le contexte. Avec PHP, c'est le système d'exploitation du serveur qui fait la différence.

  • Certains systèmes d'exploitation utilisent le caractère Carriage return : \r (vieilles générations de Mac, avant OS X).
  • D'autres utilisent le caractère Line feed : \n (systèmes Unix comme Linux et Mac).
  • D'autres utilisent la combinaison des deux : \r\n (Windows).
  • Il est possible d'utiliser la constante PHP_EOL pour effectuer un saut de ligne qui sera compatible avec tous les systèmes d'exploitation. Elle devra être placée en dehors des apostrophes ou des guillemets.

Pour faciliter la consultation du fichier journal

Il est conseillé de vider régulièrement le fichier journal. Ceci vous évitera d'avoir à défiler le contenu jusqu'au bas du fichier pour retrouver les messages récents.

Par défaut, le fichier journal s'ouvrira avec le bloc notes. Le problème avec ce logiciel, c'est qu'il ne permet pas de rafraîchir le contenu d'un fichier une fois qu'il a été ouvert. Vous seriez continuellement obligés de fermer puis de réouvrir votre fichier journal.

Vous devriez ouvrir le fichier journal à l'aide de Geany.

Avec Geany, vous pourrez garder le fichier journal ouvert tout au long de votre travail de débogage. En effet, lorsque Geany prendra le focus et réalisera que le fichier a été modifié, il vous demandera si vous désirez le recharger. Génial !

Pour plus d'information

« error_log ». PHP. http://php.net/manual/fr/function.error-log.php

« Ultimate Guide to Logging ». Solarwinds Loggly. https://www.loggly.com/ultimate-guide/php-logging-basics/

« Using error_log() with print_r() to gracefully debug PHP ». Open Mutual – Company Blog. http://www.openmutual.org/2012/01/using-error_log-with-print_r-to-gracefully-debug-php/

Les liens suivants permettent de comprendre la différence entre define() et const.

« Les constantes ». PHP. http://php.net/manual/fr/language.constants.php

« Constantes de classe ». PHP. http://php.net/manual/fr/language.oop5.constants.php

Veuillez noter que le contenu de cette fiche vous est partagé à titre gracieux, au meilleur de mes connaissances et sans aucune garantie.
Par Christiane Lagacé
Dernière révision le 17 janvier 2024
Merci de partager !

Site fièrement hébergé chez A2 Hosting.

Soumettre