Using JLog

Using JLog can be very useful in components when analysing the performance of custom extensions - or analysing where extensions are giving issues. Note this should be used in tandem with php exceptions - not as a replacement. See Exceptions and Logging in Joomla 1.7 and Joomla Platform 11.1 for more information on this

Calling the class

To use JLog you need to call the JLog class. Done through the following code:

   jimport('joomla.log.log');

Basic File Logging

Often you may wish to display an error log message and log to an error file. Joomla allows this natively through the JLog::add function. For example:

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

Adding the category of jerror means that this message will also be displayed to users. To only write to file you can easily drop that parameter and simply use

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

Logging a specific extension

Sometimes it may be useful to log the errors to a specific file. In this case you can

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

Now remember to change the category when you add a log message. Such as in the example below.

   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.

Logging specific priorities

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.