Using JLog/nl

Het gebruik van "'JLog"' kan zeer nuttig zijn in componenten bij het analyseren van de prestaties van de maatwerk extensies - of analyseren waar extensies problemen geven. Merk op dat dit moet worden gebruikt in combinatie met php exceptions - niet als een vervanging. Zie Exceptions en het Inloggen in Joomla 1.7 en Joomla Platform 11.1 voor meer informatie hierover.

Het aanroepen van de klasse

Om JLog te gebruiken, moet je de JLog klasse aanroepen. Dat gaat met de volgende code:

   jimport('joomla.log.log');

Basisbestand Logging

Vaak kun je behoefte hebben aan een foutbericht en wil je deze registreren in de Logging. Joomla staat dit toe via de JLog::add functie. Bij voorbeeld:

   JLog::add(JText::_('JTEXT_ERROR_MESSAGE'), JLog::WARNING, 'jerror');

Het toevoegen van de categorie van jerror betekent dat dit bericht ook wordt weergegeven aan gebruikers. Om alleen naar bestand te schrijven, kunt u simpelweg de parameter vergeten en gebruik maken van:

   JLog::add(JText::_('JTEXT_ERROR_MESSAGE'), JLog::WARNING);

Het aanmelden van een specifieke extensie

Soms kan het handig zijn om de fouten te loggen naar een specifiek bestand. Je kunt In dit geval:

   JLog::addLogger(
       array(
            // Sets file name
            'text_file' => 'com_helloworld.errors.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, still
       // we need to put it inside an array
       array('com_helloworld')
   );

Nu moet u niet vergeten de categorie te wijzigen wanneer u een logbericht toevoegt. Zoals in het voorbeeld hieronder.

   JLog::add(JText::_('JTEXT_ERROR_MESSAGE'), JLog::WARNING, 'com_helloworld');

Note: You may wish to combine this with the Display error messages and notices section to display visable error notifications to users.

Vastleggen van specifieke prioriteiten

You can also add an additional logger to capture only critical and emergency log notifications:

   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')
   );

You can also exclude a specific category from being included. For example, to log all but DEBUG messages:

   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')
   );

Notice how bitwise operations (bitwise AND, &; and bitwise NOT, ~) are used to calculate the accepted log levels.

Formatting the logfile

The first parameter to addLogger can have a few optional additional settings in addition to the text_file entry.

There is for example the entry text_entry_format, specifying the format of each line in your logfile.

The default format is:

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

Here is an example of a different format which shows how to omit the category:

   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')
   );

In addition to the placeholders shown above in the default string, the following values are available:

   {CLIENTIP}
   {TIME}
   {DATE}

There is an additional optional boolean parameter text_file_no_php, which specifies whether the log file is prepended with the usual prefix of:

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

Note: Usually you should not set this setting to false. Log files should not be readable from the outside, since they can provide valuable information about your system for attackers. Only dabble with this if you know what you're doing!

Furthermore, if you want to store the log file somewhere else than the logging path configured in the Joomla! settings, you can there is the text_file_path setting.