Actions and filters (hooks)

With the help of hooks in WordPress you can modify how Simple History works. You can for example change who can see the log and customize what is logged.

Actions and filters are prefixed with simple_history/, for example 'simple_history/log/do_log'.

💡 For more information on how to use hooks in WordPress see the hooks documentation on wordpress.org.

There are many actions and filters in the plugin. For a list of all see the source code of the plugin. You can search the code on GitHub for all hooks (requires that you are logged in to GitHub).

Below is some of filters and actions that are most commonly used among the users of the plugin.

Examples

• simple_history/add_custom_logger
• simple_history/log/inserted
• simple_history/dashboard_pager_size
• simple_history/db_purge_days_interval
• simple_history/log/do_log
• simple_history/log/do_log/{$logger_slug}
• simple_history/log/do_log/{$logger_slug}/{$message_key}
• simple_history/pause
• simple_history/resume
• simple_history/maps_api_key
• simple_history/privacy/anonymize_ip_address
• simple_history/get_log_row_plain_text_output/output
• simple_history/log_insert_context

simple_history/add_custom_logger

do_action(
  'simple_history/add_custom_logger', 
  Simple_History $simple_history
);Code language: PHP (php)

Fires after the list of loggers to load are populated. Can for example be used by plugins to load their own custom loggers.

See register_logger() for more info.

simple_history/log/inserted

do_action(
    'simple_history/log/inserted',
    array $context,
    array $data_parent_row,
    Logger $logger
);Code language: PHP (php)

Fired after an event has been logged.

• @param array $context Array with all context data that was used to log event.
• @param array $data_parent_row Array with data used for parent row.
• @param Logger $instance Reference to this logger instance.

simple_history/dashboard_pager_size

apply_filters(
  'simple_history/dashboard_pager_size',
  int $pager_size
)Code language: PHP (php)

Filter the pager size setting for the dashboard.

simple_history/db_purge_days_interval

apply_filters(
  'simple_history/db_purge_days_interval',
  int $days
)Code language: PHP (php)

Filter to modify number of days of history to keep. Default is 60 days.

Example: Keep only the most recent 7 days in the log:

add_filter(
  "simple_history/db_purge_days_interval", 
  function( $days ) {
    $days = 7;
    return $days;
  }
);
Code language: PHP (php)

Example: Expand the log to keep 90 days in the log.

add_filter(
  "simple_history/db_purge_days_interval", 
  function( $days ) {
    $days = 90;
    return $days;
  }
);Code language: PHP (php)

simple_history/log/do_log

apply_filters(
    'simple_history/log/do_log',
    bool $doLog,
    string $level,
    string $message,
    array $context,
    Logger $logger
)
Code language: PHP (php)

• @param bool $doLog Whether to log or not.
• @param string $level The loglevel.
• @param string $message The log message.
• @param array $context The message context.
• @param Logger $instance Logger instance.

Example: Disable all logging.

add_filter(
  'simple_history/log/do_log',
  '__return_false'
)Code language: JavaScript (javascript)

Example: Do not log some post types, for example pages and attachments in this case.

add_filter(
     'simple_history/log/do_log',
     function ( $do_log = null, $level = null, $message = null, $context = null, $logger = null ) {

         $post_types_to_not_log = array(
             'page',
             'attachment',
         );

         if ( ( isset( $logger->slug ) && ( $logger->slug === 'SimplePostLogger' || $logger->slug === 'SimpleMediaLogger' ) ) && ( isset( $context['post_type'] ) && in_array( $context['post_type'], $post_types_to_not_log ) ) ) {
             $do_log = false;
         }

         return $do_log;
     },
     10,
     5
 );Code language: PHP (php)

simple_history/log/do_log/{$logger_slug}

apply_filters(
  "simple_history/log/do_log/{$logger_slug}",
  bool $do_log
)Code language: PHP (php)

Example filter names:

• simple_history/log/do_log/SimpleUserLogger
• simple_history/log/do_log/SimplePostLogger

Example: Disable logging of any user login/logout/failed login activity:

add_filter(
  'simple_history/log/do_log/SimpleUserLogger', 
  '__return_false'
);Code language: JavaScript (javascript)

simple_history/log/do_log/{$logger_slug}/{$message_key}

apply_filters( 'simple_history/log/do_log/{$logger_slug}/{$message_key}')Code language: JavaScript (javascript)

Easy shortcut method to disable logging of messages from a specific logger and message.

Example filter names:

• simple_history/log/do_log/SimpleUserLogger/user_logged_in
• simple_history/log/do_log/SimplePostLogger/post_updated

simple_history/pause

do_action('simple_history/pause')

Disables logging completely until next page load or until simple_history/resume is triggered.

Useful for example when importing many things using PHP because then the log can be overwhelmed with data.

A code snippet to show the behavior:

// Creation of this post be logged.
wp_insert_post(array(
    'post_title' => 'Test before pause (will be logged) ' . time(),
    'post_content' => 'Test',
    'post_status' => 'publish',
    'post_type' => 'post',
));

// Pause logging.
do_action('simple_history/pause');

// Creation of these 100 posts will not be logged.
for ( $i = 0; $i < 100; $i++ ) {
    wp_insert_post(array(
        'post_title' => 'Test after pause (should not be logged) ' . time(),
        'post_content' => 'Test',
        'post_status' => 'publish',
        'post_type' => 'post',
    ));
}

// Enable logging again.
do_action('simple_history/resume');

// Creation of this this post it logged.
wp_insert_post(array(
    'post_title' => 'Test after resume (should be logged again) ' . time(),
    'post_content' => 'Test',
    'post_status' => 'publish',
    'post_type' => 'post',
));Code language: PHP (php)

simple_history/resume

See documentation for simple_history/pause.

simple_history/maps_api_key

Allows you to set an API key to use for Google Maps to show an image of the location for successful and failed login attempts.

// Use filter to set API key that we own.
add_filter(
    'simple_history/maps_api_key',
    function() {
        return 'your-google-maps-key';
    }
);Code language: JavaScript (javascript)

After supplying your API key Simple History can render a map when you click the IP address of for example a successful login:

By default Simple History anonymizes the IP addresses, meaning that the IP address that is geolocated is the first adress on the anonymized subnet. So if the stored IP address is 142.250.75.x then the IP address used to found location will be 142.250.75.0. This means that the location results can be faulty, since the user could have had address 142.250.75.96 that potentially could be located somewhere else.

To overcome this you can use a filter to allow storing the full IP address. See simple_history/privacy/anonymize_ip_address for more info.

simple_history/privacy/anonymize_ip_address

$anonymize_ip_address = apply_filters(
    'simple_history/privacy/anonymize_ip_address',
    true
);Code language: PHP (php)

Filter to control if an IP addresses should be anonymized or not. Defaults to true, meaning that any IP address is anonymized. This is due to GDPR reasons.

<?php
// Disable IP anonymization to allow full
// IP address to be added to events.
// e.g. "17.253.144.10" will be stored
// instead of "17.253.144.x".
add_filter( 'simple_history/privacy/anonymize_ip_address', '__return_false' );
Code language: HTML, XML (xml)

simple_history/get_log_row_plain_text_output/output

/**
 * Filter the plain text output for a log row.
 *
 * @since 4.6.0
 *
 * @param string $output Plain text output for a log row.
 * @param object $row Log row object.
 * @param Logger $logger Logger instance.
 */
$output = apply_filters(
	'simple_history/get_log_row_plain_text_output/output',
	$logger->get_log_row_plain_text_output( $row ),
	$row,
	$logger
);
Code language: PHP (php)

Filters the “plain text” message output. The output can be for example “Updated page ‘About the company’” and using this filter you can prepend or append text to the message.

Examples: Add post id to each post or WooCommerce event.

simple_history/log_insert_context

Filters the context to store for this event/row

/**
 * Filters the context to store for this event/row
 * @param array $context Array with all context data to store. Modify and return this.
 * @param array $data Array with data used for parent row.
 * @param Logger $logger Reference to logger instance.
 */
$context = apply_filters(
	'simple_history/log_insert_context',
	$context,
	$data,
	$logger
);Code language: PHP (php)