Logging

Logging API

You can add messages to the history log from your own code, for example in a custom plugin or from your theme.

Using filters

Adding messages

The easiest and most safe way to log messages is using the 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'
);

Jane DoeApril 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'
);

Jane DoeApril 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'
);

Jane DoeApril 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' );

Jane DoeApril 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!' );

Jane DoeApril 5, 2022 - 22:23 (25 days ago)

User "Jessie" deleted user "Kim"warning

Jane DoeApril 5, 2022 - 22:23 (25 days ago)

Space is running low on the hard drive!alert

Jane DoeApril 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'
	]
);

Jane DoeApril 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',
		]
	);
}

Jane DoeApril 5, 2022 - 22:23 (25 days ago)

This is a message sent to the log

+2 similar events

Jane DoeApril 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 SimpleLoggerLogInitiators 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' => SimpleLoggerLogInitiators::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' => SimpleLoggerLogInitiators::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' => SimpleLoggerLogInitiators::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' => SimpleLoggerLogInitiators::WEB_USER,
	]
);

jessApril 5, 2022 - 22:23 (25 days ago)

User jessie edited page My test page

WordPressApril 5, 2022 - 22:23 (25 days ago)

WordPress updated itself from version 3.8 to 3.8.1

WP-CLIApril 5, 2022 - 22:23 (25 days ago)

Updated plugin Query Monitor from version 3.8.2 to version 3.9.0

WEB_USERApril 5, 2022 - 22:23 (25 days ago)

An attempt to login as user 'administrator' failed to login because the wrong password was entered