You can add messages to the history log from your own PHP code, for example in a custom WordPress plugin or from your WordPress theme.
Using filters
Adding messages
The easiest and most safe way to log messages is using the WordPress PHP function apply_filters.
👍 Because apply_filters is a function that is built into WordPress your site won’t break if Simple History is not available, for example if the plugin has been disabled.
apply_filters(
'simple_history_log',
'This is a logged message'
);Code language: PHP (php)
Jane Doe • April 5, 2022 – 22:23 (25 days ago)
This is a logged message
Adding log level
By default messages are added with log level info. If you need to log something that has a higher severity then you can specify the log level using a fourth parameter:
apply_filters(
'simple_history_log',
'This is another logged message, with another severity level',
null,
'warning'
);Code language: JavaScript (javascript)
Jane Doe • April 5, 2022 – 22:23 (25 days ago)
This is another logged message, with another severity levelwarning
Adding context
You can also add messages with context:
apply_filters(
'simple_history_log',
'User {username} created a compressed backup with the name {backup_name} with format {backup_format}',
[
'username' => 'Jane',
'backup_name' => 'orders-backup.zip',
'backup_format' => 'CSV'
],
'alert'
);Code language: PHP (php)
Jane Doe • April 5, 2022 – 22:23 (25 days ago)
User Jane created a compressed backup with the name orders-backup.zip with format CSValert
Using SimpleLogger()
Adding messages
If you are sure that Simple History is loaded you can use function SimpleLogger() to log things. This method may be prefered if you log a lot of things, use many variables, need to manually add initiator, or just because it looks cooler 😎.
💡 To be sure nothing breaks if Simple History is disabled you can for example wrap each of the calls below inside a function_exists( 'SimpleLogger' ).
Add a simple information message to the log:
SimpleLogger()->info( 'This is a message added to the log' );Code language: PHP (php)Jane Doe • April 5, 2022 – 22:23 (25 days ago)
This is a message added to the log
Adding log level
You can add messages with different severity using any of the log levels specified in PSR-3: “info” (default), “notice”, “warning”, and so on:
SimpleLogger()->warning( 'User "Jessie" deleted user "Kim"' );
SimpleLogger()->alert( 'Space is running low on the hard drive!' );
SimpleLogger()->debug( 'Ok, cron job is running!' );Code language: PHP (php)Jane Doe • April 5, 2022 – 22:23 (25 days ago)
User “Jessie” deleted user “Kim”warning
Jane Doe • April 5, 2022 – 22:23 (25 days ago)
Space is running low on the hard drive!alert
Jane Doe • April 5, 2022 – 22:23 (25 days ago)
Ok, cron job is running!debug
Adding context
Log entries can have placeholders and context. This makes log entries translatable and filterable. And it also makes it easier to find all messages of the same type when searching. The values that you add in the context array does not need to have a corresponding placeholder name in the message, so it’s possible to add some extra information that is only visible when viewing more details about an event.
SimpleLogger()->notice(
'User {username} edited page {pagename}',
[
'username' => 'jessie',
'pagename' => 'My test page',
'page_id' => 124,
'some_nice_to_have_extra_value' => 'My useful extra value'
]
);Code language: PHP (php)Jane Doe • April 5, 2022 – 22:23 (25 days ago)
User jessie edited page My test page
Note that page_id and some_nice_to_have_extra_value are saved to the database, but they are not shown in the main log feed.
Automatic grouping of messages
If many entries of the same kind is logged the activity feed can be a bit crowded with messages. That’s why Simple History by defaults groups similar messages, for example login attempts or post updates. If a user is editing a page on your website they may edit the page many times and we don’t want the edit of a single post to take over the feed completely.
// Add a message to the history log
// and then add a second log entry with same info and Simple History
// will make these two become an "occasionGroup",
// i.e. collapsing their entries into one expandable log item.
SimpleLogger()->info( 'This is a message sent to the log' );
SimpleLogger()->info( 'This is a message sent to the log' );
// Log entries can have custom occasionsID.
// This will group items together and a log entry will only be shown once
// in the log overview, even if the logged messages are different.
for ( $i = 0; $i < rand( 1, 50 ); $i++ ) {
SimpleLogger()->notice(
'User {username} edited page {pagename}',
[
'username' => "example_user_{$i}",
'pagename' => 'My test page',
'_occasionsID' => 'postID:24884,action:edited',
]
);
}Code language: PHP (php)
Jane Doe • April 5, 2022 – 22:23 (25 days ago)
This is a message sent to the log
+2 similar events
Jane Doe • April 5, 2022 – 22:23 (25 days ago)
User {example_user_0} edited page My test page
+24 similar events
Initiator
By default Simple History automatically determines who is responsible for something that happens. You can however override this if needed by adding an _initiator key to the context array.
The available initiators are specified in the LogInitiators class and they are:
- WP_USER
- WEB_USER
- WORDPRESS
- WP_CLI
- OTHER
// Events can have different "initiators",
// i.e. who was responsible for the logged event
// Initiator "WORDPRESS" means that WordPress did something on it's own
SimpleLogger()->notice(
'User {username} edited page {pagename}',
[
'username' => 'jessie',
'pagename' => 'My test page',
'_initiator' => LogInitiators::WP_USER,
'_user_id' => 5,
'_user_login' => 'jess',
'_user_email' => 'jessie@example.com',
]
);
SimpleLogger()->info(
'WordPress updated itself from version {from_version} to {to_version}',
[
'from_version' => '3.8',
'to_version' => '3.8.1',
'_initiator' => LogInitiators::WORDPRESS,
]
);
// Initiator "WP_USER" means that a logged in user did something
SimpleLogger()->info(
'Updated plugin {plugin_name} from version {plugin_from_version} to version {plugin_to_version}',
array(
'plugin_name' => 'Query Monitor',
'plugin_from_version' => '3.8.2',
'plugin_to_version' => '3.9.0',
'_initiator' => LogInitiators::WP_CLI,
)
);
// Initiator "WEB_USER" means that an unknown internet user did something
SimpleLogger()->warning(
"An attempt to login as user 'administrator' failed to login because the wrong password was entered",
[
'_initiator' => LogInitiators::WEB_USER,
]
);Code language: PHP (php)jess • April 5, 2022 – 22:23 (25 days ago)
User jessie edited page My test page
WordPress • April 5, 2022 – 22:23 (25 days ago)
WordPress updated itself from version 3.8 to 3.8.1
WP-CLI • April 5, 2022 – 22:23 (25 days ago)
Updated plugin Query Monitor from version 3.8.2 to version 3.9.0
WEB_USER • April 5, 2022 – 22:23 (25 days ago)
An attempt to login as user ‘administrator’ failed to login because the wrong password was entered