Manual:Logging to Special:Log
Appearance
This page describes how to log actions to Special:Log
.
(Logging to the application log is covered at Manual:Structured logging .)
Example
[edit]This 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]The following should work in extension.json
:
{
"LogTypes": [ "foo" ],
"LogNames": {
"foo": "foo-name"
},
"LogHeaders": {
"foo": "foo-header"
},
"LogActionsHandlers": {
"foo/*": "LogFormatter"
}
}
This page is outdated. |
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( [
'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 LogFormatter for an example LogFormatter with links.
See also
[edit]- Manual:$wgLogTypes
- Manual:$wgLogActions
- Manual:$wgLogNames
- Manual:$wgLogHeaders
- Manual:$wgLogActionsHandlers
- Manual:$wgLogRestrictions
- Manual:$wgFilterLogTypes
- Manual:$wgActionFilteredLogs
- task T26620 - Log entries are difficult to localize; rewrite logs system