Joomla! Documentation™

Vue d'ensemble

La journalisation de Joomla vous donne la possibilité d'enregistrer des messages dans des fichiers et à l'écran (dans la console de débogage de Joomla ! au bas de la page Web) et la principale classe de Joomla qui sous-tend cette fonction est JLog. Dans la nouvelle convention d'appellation, il s'agit de la classe Log dans l'espace de noms Joomla\CMS\Log\Log.

La journalisation peut être contrôlée dynamiquement par la configuration globale de Joomla et par la configuration du plugin System - Debug (livré avec Joomla). Globalement, ces fonctionnalités vous permettent de :

• Activez ou désactivez la journalisation DEBUG - de sorte que vous ne consommiez pas de ressources inutilement, mais que vous disposiez des informations de journalisation pour faciliter le dépannage en cas de problème, par exemple sur un site actif sur lequel votre extension est installée.
• acheminer les messages de journalisation vers un fichier de journalisation spécifique à votre propre extension.
• Afficher les messages de journal dans la console de débogage - vous pouvez sélectionner le groupe d'utilisateurs auxquels les messages de journal doivent être affichés, de sorte que sur un site en direct, les développeurs peuvent voir les messages tandis que les autres utilisateurs ne sont pas affectés.
• filtrer les messages de la console de débogage par priorité (c'est-à-dire INFO, DEBUG, WARNING, etc.) et par catégorie. (Vous êtes libre de définir vos propres catégories).

En outre, les messages du journal peuvent être traduits dans différentes langues.

Les principales options de configuration relatives à la journalisation sont présentées ci-dessous. L'activation du débogage et l'affichage de la console de débogage de Joomla sont contrôlés par les options de configuration globale.

La journalisation vers le fichier journal général est contrôlée via l'onglet Logging de la configuration du plugin Joomla System - Debug. (Dans le menu administrateur, cliquez sur Extensions / Plugins, trouvez le plugin System - Debug. Cliquez dessus pour modifier ses options configurables).

Les options de l'onglet Plugin s'affichent dans la console de débogage de Joomla.

Fichier journal de base

Pour enregistrer un message, vous utilisez la fonction JLog::add(). Par exemple :

JLog::add('my error message', JLog::ERROR, 'my-error-category');

En utilisant la nouvelle convention de dénomination des classes, utiliser à la place :

use Joomla\CMS\Log\Log;
Log::add('my error message', Log::ERROR, 'my-error-category');

Les paramètres sont

1. Une chaîne de messages. Vous pouvez utiliser la traduction avec ceux-ci. (Par exemple, JText::_('MY_EXTENSION_ERR_MSG') Vous pouvez également afficher les valeurs des variables, à condition de les convertir dans un format de chaîne de caractères. (Par exemple, en utilisant __toString() si le type de la variable le supporte).
2. Une priorité, qui peut être l'une des suivantes : JLog::EMERGENCY, JLog::ALERT, JLog::CRITICAL, JLog::ERROR, JLog::WARNING, JLog::NOTICE, JLog::INFO, JLog::DEBUG (basée sur les niveaux de gravité standard de syslog / RFC 5424 - voir wikipedia article on syslog).
3. Une catégorie, qui est juste une chaîne de texte. Vous pouvez définir les catégories que vous voulez, mais il est préférable de les définir pour éviter les conflits possibles avec celles d'autres extensions.

Il peut être très utile pour le dépannage des problèmes si vous incluez des messages de débogage de diagnostic dans votre extension. Dans ce cas, enfermez votre message de journal dans une vérification de JDEBUG :

if (JDEBUG)
{
    JLog::add('my debug message', JLog::DEBUG, 'my-debug-category');
}

Exemple de code de journalisation de base

Vous trouverez ci-dessous le code d'un module Joomla simple que vous pouvez installer et exécuter pour démontrer l'utilisation de la fonctionnalité de journalisation. Si vous n'êtes pas sûr du développement et de l'installation d'un module Joomla, vous pouvez suivre le tutoriel à l'adresse suivante : Création d'un module simple .

Dans un dossier mod_sample_log, créez les 2 fichiers suivants :

mod_sample_log.xml

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.1" client="site" method="upgrade">
    <name>Joomla Log demo</name>
    <version>1.0.1</version>
    <description>Code demonstrating use of Joomla Log class to log messages</description>
    <files>
        <filename module="mod_sample_log">mod_sample_log.php</filename>
    </files>
</extension>

mod_sample_log.php

<?php
defined('_JEXEC') or die('Restricted Access');

use Joomla\CMS\Log\Log;

Log::add('my error message', Log::ERROR, 'my-error-category');

JLog::add('my old error message', JLog::WARNING, 'my-old-error-category');

echo "Error message logged";

Compressez le répertoire mod_sample_log pour créer mod_sample_log.zip.

Dans votre administrateur Joomla, allez dans Installer les extensions et via l'onglet Télécharger le fichier de paquet, sélectionnez ce fichier zip pour installer cet exemple de module de journal.

Rendez ce module visible en le modifiant (cliquez dessus dans la page Modules) puis :

1. rendre son statut publié
2. sélectionner une position sur la page pour qu'il soit affiché
3. Dans l'onglet "Affectation des menus", indiquez les pages sur lesquelles il doit apparaître.

Vérifiez la configuration des paramètres indiqués en haut de cette page Web. En particulier, assurez-vous que le plugin System - Debug est activé et que l'option Log Almost Everything est définie sur Oui. Notez également l'emplacement du dossier où sont stockés vos fichiers journaux.

Affichez votre site Joomla et vous devriez alors voir apparaître l'exemple de module de journal. Dans votre dossier de fichiers journaux, vous devriez trouver vos messages d'erreur dans le fichier everything.php.

Activez également la console de débogage et confirmez que vous pouvez voir les messages d'erreur dans sa section Messages du journal.

Consignation dans un fichier journal spécifique

Vous pouvez utiliser JLog::addLogger() pour configurer la journalisation vers un fichier journal supplémentaire, en filtrant les messages à y envoyer par priorité (le "niveau de gravité") et/ou par catégorie. Les paramètres de JLog::addLogger() sont :

1. un tableau avec les détails de la configuration - y compris le nom du fichier journal.
2. les niveaux de gravité à consigner dans ce fichier.
3. un tableau des catégories à enregistrer dans ce fichier. (Si le paramètre 4 est défini à true, ce tableau définit les catégories qui ne doivent PAS être enregistrées dans le fichier).
4. (souvent omis) un booléen spécifiant si le paramètre 3 est une liste d'inclusion. (La valeur par défaut, P4 = false) ou une liste d'exclusion (P4 = true.)

Par exemple, si vous avez développé une extension com_helloworld, vous pouvez utiliser ce qui suit :

JLog::addLogger(
    array(
         // Sets file name
         'text_file' => 'com_helloworld.log.php'
    ),
    // Sets messages of all log levels to be sent to the file.
    JLog::ALL,
    // The log category/categories which should be recorded in this file.
    // In this case, it's just the one category from our extension.
    // We still need to put it inside an array.
    array('com_helloworld')
);

Ensuite, lorsque vous enregistrez un message, spécifiez la catégorie com_helloworld, comme dans l'exemple suivant

JLog::add(JText::_('COM_HELLOWORLD_ERROR_MESSAGE_123'), JLog::ERROR, 'com_helloworld');

Votre message sera alors écrit dans le fichier com_helloworld.log.php. Si les paramètres du plugin System - Debug sont réglés sur "Log Almost Everything", le message apparaîtra également dans le fichier journal commun everything.php.

Note: Vous pouvez combiner cette section avec la section Afficher les messages d'erreur et les avis pour afficher des notifications d'erreur visibles aux utilisateurs.

Vous pouvez également ajouter un journal des enregistrements pour récupérer uniquement les notifications critiques et d'urgence :

JLog::addLogger(
    array(
         // Sets file name.
         'text_file' => 'com_helloworld.critical_emergency.php'
    ),
    // Sets critical and emergency log level messages to be sent to the file.
    JLog::CRITICAL + JLog::EMERGENCY,
    // The log category which should be recorded in this file.
    array('com_helloworld')
);

Vous pouvez également exclure une catégorie spécifique. Par exemple, pour tout enregistrer sauf les messages de débogage DEBUG :

JLog::addLogger(
    array(
         // Sets file name.
         'text_file' => 'com_helloworld.all_but_debug.php'
    ),
    // Sets all but DEBUG log level messages to be sent to the file.
    JLog::ALL & ~JLog::DEBUG,
    // The log category which should be recorded in this file.
    array('com_helloworld')
);

Les niveaux de priorité de JLog sont implémentés comme des bits distincts d'un entier, de sorte que vous pouvez utiliser des opérations bit à bit. (par bit AND, &; et par bit NOT, ~) pour calculer les niveaux de journal appropriés. JLog::All est un nombre entier constant dont tous les bits pertinents sont activés, de sorte que tous les niveaux de priorité de Joomla sont inclus.

Formatage du fichier log

Le premier paramètre addLogger peut comporter différentes options facultatives supplémentaires en plus de l'ntrée text_file.

Il existe par exemple l'entrée text_entry_format, précisant le format pour chaque ligne de votre fichier log.

Le format par défaut est :

   '{DATETIME} {PRIORITY}      {CATEGORY}      {MESSAGE}'

Voici un exemple d'un format différent qui montre comment omettre la catégorie :

JLog::addLogger(
    array(
         // Sets file name.
         'text_file' => 'com_helloworld.critical_emergency.php',
         // Sets the format of each line.
         'text_entry_format' => '{DATETIME} {PRIORITY} {MESSAGE}'
    ),
    // Sets all but DEBUG log level messages to be sent to the file.
    JLog::ALL & ~JLog::DEBUG,
    // The log category which should be recorded in this file.
    array('com_helloworld')
);

En plus des espaces réservés indiqués ci-dessus dans la chaîne par défaut, les valeurs suivantes sont disponibles :

   {CLIENTIP}      (this is the IP address of the client)
   {TIME}
   {DATE}

Il existe a un autre paramètre booléen optionnel text_file_no_php qui permet de spécifier si le fichier journal est ajouté avec le préfixe de :

   #
   #<?php die('Forbidden.');?>

Remarque : en général, vous ne devez pas définir ce paramètre à false. Les fichiers de journaux ne doivent pas être lisible depuis l'extérieur car ils peuvent fournir aux attaquants des informations précieuses sur votre système. Intéressez-vous à cela uniquement si vous maîtrisez le sujet !

En outre, si vous souhaitez stocker le fichier log ailleurs que dans le chemin d'accès configuré dans vos paramètres Joomla, cela est possible et voice le paramètre text_file_path.

Se connecter à d'autres endroits

En plus de la journalisation vers des fichiers, vous pouvez également vous connecter à d'autres endroits, tels que .

• la zone de message de Joomla (où le message est affiché si vous appelez JFactory::getApplication()->enqueueMessage()).
• une table de base de données.
• une simple instruction echo.

Parmi ces éléments, le plus utile est probablement la journalisation dans la barre de messages, que vous pouvez configurer via :

JLog::addLogger(array('logger' => 'messagequeue'), JLog::ALL, array('msg-error-cat')) ;

Ensuite, lorsque vous faites :

JLog::add('une erreur à afficher', JLog::ERROR, 'msg-error-cat') ;

vous obtiendrez le message copié dans la barre de message. Notez que le code central de Joomla configure la journalisation vers la file d'attente des messages pour la catégorie 'jerror', de sorte que si vous utilisez cette catégorie dans vos messages de journalisation, vous obtiendrez le message affiché dans la barre de messages.' Par exemple :

JLog::add('error copied to message bar', JLog::Error, 'jerror') ;

aura pour effet d'afficher le message dans la zone de messages de Joomla, même si vous n'avez pas explicitement configuré un enregistreur pour qu'il s'y enregistre.

PSR-3 Logger

Depuis la version 3.8, Joomla intègre un logger qui adhère à la PSR-3 Logger Interface. Cela permet aux bibliothèques qui suivent cette recommandation standard de s'intégrer au système de journalisation de Joomla. Pour l'utiliser, il faut d'abord faire :

use Joomla\CMS\Log\Log;
$psr3Logger = Log::createDelegatedLogger();

Cela renvoie un objet sur lequel vous avez à disposition les méthodes de la PSR-3 LoggerInterface, par exemple :

$psr3Logger->critical("critical error text", array("category" => "my-critical-category"));

Les journaux par défaut de Joomla ne traitent que les éléments "catégorie" et "date" du tableau associatif context (paramètre 2), en faisant correspondre les valeurs de ces éléments à la colonne correspondante de votre fichier journal.

Exceptions

JLog::add() lancera une exception s'il ne peut pas écrire dans le fichier journal. Pour éviter cela, vous devrez soit envelopper l'appel dans une autre fonction, soit implémenter votre propre classe de logger et l'inclure avec :

JLog::addLogger(
    array(
         // Use mycustomlogger.
         'logger' => 'mycustomlogger',
         'text_file' => 'com_helloworld.errors.php'
    ),
    JLog::ALL,
    array('com_helloworld')
);

En savoir plus

La journalisation Joomla doit être utilisée en tandem avec les exceptions PHP, pas en remplacement. Voir J2.5:Exceptions_and_Logging_in_Joomla_Platform_11.1_and_Joomla_2.5 pour l'historique de cette classe et comment elle est née des anciennes classes d'erreurs compatibles PHP4 de Joomla.