Logging to a file only with JLog

Question

I believe the JLog documentation is incorrect with this:

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::a dd(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::a dd(JText::_('JTEXT_ERROR_MESSAGE'), JLog::WARNING);

I've found the exact opposite in J3.3. When I use:

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

It logs to the user as well. If I add the category it doesn't.

Can someone confirm that I'm not going nuts or explain my misunderstanding?

If I'm right, how do you go about contributing a documentation change request?

Answer 1

This is the way I use to add a log entry to a file. JLog::add has changed too much between Joomla versions.

$config = array(
    'text_file' => 'logging.log'
);

// Joomla 3
jimport('joomla.log.logger.formattedtext');
$logger = new JLogLoggerFormattedtext($config);

// Joomla 2.5   
// jimport('joomla.log.loggers.formattedtext');
// $logger = new JLoggerFormattedText($config);

// Comment is a string
// $status can be JLog::INFO, JLog::WARNING, JLog::ERROR, JLog::ALL, JLog::EMERGENCY or JLog::CRITICAL
$entry = new JLogEntry($comment, $status);
$logger->addEntry($entry);

Answer 2

I've been updating the JLog Documentation page referred to above, to (hopefully) make it accurate. So if anyone who's watching this question could check it out and raise any problems (as comments on this answer), then that would be much appreciated.

With regard to the specific question, I've got Joomla 3.7 running and it has core code in libraries/cms.php which sets up a logger to the 'messagequeue':

JLog::addLogger(array('logger' => 'messagequeue'), JLog::ALL, array('jerror'));

And then anything with a category of 'jerror' gets copied to this logger, which then displays the message to the user via the JFactory::getApplication()->enqueueMessage() method.

As regards getting a change to the Joomla documentation, you should sign up to contributing to joomla documentation (eg How to Contribute to Joomla Documentation, and then either mark the page as needing attention (plus the reason), or you can also just fix it yourself.

But I think in this case, that the documentation was correct, and that it was a temporary bug in the code, as described in Joomla issue re JLog.