28.5 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.

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.

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 :

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 devraient ê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.

Enregistrer une information dans le fichier journal personnalisé

La fonction PHP 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.

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

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

Donc, pour que l'écriture puisse être effectuée, le dossier log doit exister.

Si PHP n'arrive toujours pas à créer le fichier journal, c'est peut-être parce que l'usager utilisé par le serveur HTTP ne détient pas les droits requis pour l'écriture dans ce dossier.

Fonction log_debug()

Pour enregistrer vos messages de débogage dans un fichier journal, je vous propose une fonction qui utilise error_log() pour 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()).

• Assurez-vous d'avoir défini la constante DEBUG_LOG_FILE dans le fichier configuration.inc.
• Dans le dossier include de votre projet, créez un fichier nommé ma-bibliotheque.php si ce n'est pas déjà fait.
• Dans ce fichier, déclarez une fonction nommée log_debug() ou logDebug() selon les normes de programmation de votre établissement.
• Le code de cette fonction va comme suit :
  Fichier include/ma-bibliotheque.php

  /**
   * Enregistre la date suivie d'une information de débogage dans le fichier journal (log).
   * @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 (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 (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 utiliser la fonction

Pour que la fonction log_debug() soit disponible, la page Web devra faire appel à configuration.inc de même qu'à ma-bibliotheque.php.

La fonction pourra être utilisée là où vous avez besoin de loguer une information.

autre exemple :

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