Feature Proposal: Add writeLog() to TWiki::Func

Motivation

Plugins need to be able to write log entries. Some do already now by writing to $TWiki::cfg{LogFileName}, which is not clean.

Description and Documentation

=pod

---+++ writeLog( $action, $extra, $web, $topic, $user )

Write the log for an event to the logfile.
   * =$action= - name of the event, such as ='blacklist'=.
   * =$extra= - arbitrary extra information to add to the event.
   * =$web= - web name, optional. Base web is taken if empty. Ignored if web is specified in =$topic=.
   * =$topic= - topic name, optional. Can be =Topic= or =Web.Topic=. Base topic is taken if empty.
   * =$user= - !WikiName of user, optional. Name of logged-in user is taken if not specified.
Return: none

*Since:* TWiki::Plugins::VERSION 1.4

__Example:__ Calling =TWiki::Func::writeLog( 'blacklist', 'Magic number is missing' )= 
will add a log entry like this:
<verbatim>
| 2011-01-19 - 01:13 | guest | blacklist | TWiki.TWikiRegistration | Magic number is missing | 1.2.3.4 |
</verbatim>

__Note:__ Older plugins that use =$TWiki::cfg{LogFileName}= or call the internal TWiki
function directly should be fixed to use =writeLog=.

To maintain compatibility with older TWiki releases, you can write conditional code as follows:
<verbatim>
  if( defined &TWiki::Func::writeLog ) {
    # use writeLog
    TWiki::Func::writeLog( $web, $topic, 'myevent', $extra );
  } else {
    # deprecated code if plugin is used in older TWiki releases
    $TWiki::Plugins::VERSION > 1.1
      ? $TWiki::Plugins::SESSION->writeLog( 'myevent', "$web.$topic", $extra )
      : TWiki::Store::writeLog( 'myevent', "$web.$topic", $extra );
  }
</verbatim>

=cut

Impact

Implementation

-- Contributors: PeterThoeny - 2011-01-09

Discussion

This is now accepted by the 7 days review period.

-- PeterThoeny - 2011-01-20

This is now in trunk, SVN:core/lib/TWiki/Func.pm. I changed the parameter order a bit to list optional ones last.

-- PeterThoeny - 2011-01-20