Manual:Logging to Special:Log

From MediaWiki.org
Jump to: navigation, search

This page describes how to log actions to Special:Log.

Example[edit]

This is example illustrates how you would code Special:Log entries for extensions. The log messages appear on the Special:Log page and can be filtered by, for example, the log name, user, title or date range.

In your extension setup file[edit]

For core logs, the configuration is in DefaultSettings.php.

$wgLogTypes[] = 'foo';

// You can still set
// $wgLogNames['foo'] = 'foo-name';
// $wgLogHeaders['foo'] = 'foo-header';
// 
// But you don't need to, if you follow this naming convention for your i18n messages:
//
// log-name-foo
//   for the Special:Log log name that appears in the drop-down on the Special:Log page
//
// log-description-foo
//   for the Special:Log description that appears on the Special:Log page when you filter 
//   logs on this specific log name

$wgLogActionsHandlers['foo/bar'] = 'LogFormatter';

// Or if you want catch-all, do:
$wgLogActionsHandlers['foo/*'] = 'LogFormatter';

// Or if you need some extra logic, you can write your own formatter
// (subclassing LogFormatter) and do:
$wgLogActionsHandlers['foo/*'] = 'FooLogFormatter';

In i18n/en.json file[edit]

{
	"log-name-foo": "Foo log",
	"log-description-foo": "These events track when Foo events happen in the system.",
	"logentry-foo-bar": "$1 {{GENDER:$2|did bar}} to page $3"
}

Message documentation (qqq.json):

{
	"log-name-foo": "The Special:Log log name that appears in the drop-down on the Special:Log page",
	"log-description-foo": "The Special:Log description that appears on the Special:Log page when you filter logs on this specific log name",
	"logentry-foo-bar": "The template of the log entry message"
}

In the extension code[edit]

// Anywhere in your code where you want to generate a log entry

$logEntry = new ManualLogEntry( 'foo', 'bar' ); // Log action 'bar' in the Special:Log for 'foo'
$logEntry->setPerformer( $user ); // User object, the user who performed this action
$logEntry->setTarget( $this ); // The page that this log entry affects, a Title object
$logEntry->setComment( $reason ); // Optional, user provided comment

// Optionally, add additional parameters for use in the log entry’s i18n message.
// Numbering should start from 4 and can be used in the message as $4, $5 and so on.
//
// Indexes $1, $2, and $3 are reserved
// and provide the username and target page parameters for the messages.
// $1 is a reference to the user page and user talk page in the wiki
// $2 is used to determine the gender of the user for any gender specific messages
// $3 is a reference to the page on which the action took place
//
// If you want to store stuff that should not be available in messages, don’t
// prefix the array key with a number and don’t use the colons.
// 
// The format is index:formatspecifier:name.
// Format specifier is currently unused, but in future you could say for example
// that this param is a number, format it according to the user language.
// Name is just for giving identifier for the value, and helps to debug issues
// versus unindexed list of parameters.
$logEntry->setParameters( array(
  '4::paramname' => 'customparam',
  'hiddenparam' => 'ugly stuff',
) );

// We're not done yet, we need to insert the log entry into the database.
// Insert adds it to the logging table and returns the id of that log entry.
$logid = $logEntry->insert();

// Optionally, publish the log entry in recent changes and the UDP feed of recent changes
// if we want. UDP feed is mainly used for echoing the recent change items into IRC.
// publish() takes second param with values 'rcandudp' (default), 'rc' and 'udp'.
$logEntry->publish( $logid );

Adding links[edit]

To add a link to log entries, you should pass the page name etc. in the log parameters, and format that in your LogFormatter using makePageLink(). With other methods, non-html output (like UDP feed to IRC) will be broken.

See TranslateLogFormatter for an example LogFormatter with links.

Pre 1.19[edit]

There are ways to use this system but make it forward compatible with the new system by using the message name format described above. Extra parameters are what are causing most of the issues. You can make the messages like above:

'logentry-foo-bar' => '$1 {{GENDER:$2|did bar}} to page $3',

And pass empty value for param $1, because the old system will prepend the username automatically; # for $2 to avoid automatic gender feature using the gender of the reader. Custom parameters should start at $4.

An example of adding a new log type called "foo" for your extension, using the LogPage class. In the MyExtension.php file, add:

// Internal name of the log, Special:Log/foo
$wgLogTypes[] = 'foo';
// System message containing the friendly name of the log. Shows up
// in the page title and the Special:Log dropdown
// Use 
$wgLogNames['foo'] = 'foo-name';
// System message containing the introductory text on Special:Log when this page is shown
$wgLogHeaders['foo'] = 'foo-header';

Create system messages for your extension in MyExtension.i18n.php:

$messages['en'] = array(
  ...                                                     
  'foo' => 'Foo',
  'foo-name' => 'Foo log',
  'foo-header' => 'These events track when Foo events happen in the system.',
  'foo-message' => 'A Foo event happened to article [[$1]]',
  ...
);

In the body file MyExtension_body.php, add this code, which adds entries in both Special:Log/foo and Special:RecentChanges:

global $wgTitle, $wgUser;
$log = new LogPage( 'foo' );    // See alternative below
$log->addEntry(
    'bar',
    $wgTitle,
    wfMsg( 'foo-message', $wgTitle->getFullText() ),
    array(),
    $wgUser
);

If you don't want your events to show up in Special:RecentChanges, which might cause watchlist notifications, change the constructor to:

  $log = new LogPage( 'foo', false );  // Second arg = false

See also[edit]

Log actionsManual:Log actions Events: BlockingManual:Block and unblockImportingManual:Importing revisionsMerging historiesManual:Merging historiesPage deletionManual:Page deletionPage movingManual:Page movingPage restorationManual:Page restorationPatrollingManual:PatrollingProtectionManual:ProtectionRenaming a userExtension:RenameuserRevisionDeleteManual:RevisionDeleteThankingExtension:ThanksUploadingManual:UploadingUser creationManual:User creationUser rights managementManual:User rightsMerging usersManual:Merging users

Settings: $wgLogTypesManual:$wgLogTypes$wgLogActionsManual:$wgLogActions$wgLogNamesManual:$wgLogNames$wgLogHeadersManual:$wgLogHeaders$wgLogActionsHandlersManual:$wgLogActionsHandlers$wgLogRestrictionsManual:$wgLogRestrictions$wgFilterLogTypesManual:$wgFilterLogTypes$wgActionFilteredLogsManual:$wgActionFilteredLogs

Miscellaneous: Logging to Special:LogManual:Logging to Special:LogAPIAPI:Logeventslogging tableManual:Logging tableNull revisionManual:Null revision
Language:Project:Language policy English  • 日本語 • polski