Create your own custom WordPress activity log extension

Keep a record of any WordPress change you want in the activity log

WP Activity Log offers very comprehensive logging capabilities. It is able to keep a log of a wide variety of user and system activities, including activities in certain 3rd party plugins. In certain cases, however, users may want to include additional activities in the log that are not supported by WP Activity Log out of the box.
If you would like to track additional activities, you can do so by building your own custom WordPress activity log extension. This article explains how.

How do WP Activity Log sensors work?

For every set of activities that WP Activity Log can track, there is a corresponding sensor. For example, to monitor all the logins and logouts on WordPress, the plugin has a sensor called LogInOut.php. All sensor files can be found in the following plugin directory: /wp-security-audit-log/classes/sensors/.

The activity log events

If you are unfamiliar with activity log events, read the document What are events and event IDs in the WordPress activity log? If you wish to understand how our sensors work, all the events that the plugin records in the WordPress activity log are declared in the file defaults.php, which can be found in the root directory of our plugin (/wp-content/plugins/wp-security-audit-log). Refer to the complete list of WordPress activity log event IDs for more information about available event IDs.

We provide an extension sample, which you can download from our GitHub repository. Upload the file to your plugins folder, then navigate to ‘wsal-extension-example/wp-security-audit-log/custom-sensors/My_Custom_Sensor.php’. Here you will find a base class laid out for you, ready for creating your own events. This is also where custom events will be placed. Before proceeding, however, there are some basics to cover, which we outline below.

What event IDs should you use?

When choosing event IDs for your events, it’s essential to choose a unique event ID outside our default range. This will help you ensure you don’t experience conflicts in the future. We suggest using event IDs starting at 1000000 (one million) – we do not plan on using more than 1,000,000 event IDs, so it is safe to use such event IDs.
Kindly continue reading the rest of this post for a detailed explanation of how to build your sensor.
Failure to choose a unique code will result in an error notice being shown, so do take care before proceeding further.

WP Activity Log sensors documentation and sample code

Creating your code

The code in the extension sample is fully documented, but just in case, here is a quick introduction.
First, specify a class for your custom sensor:

WSAL_Sensors_My_Custom_Sensor extends
WSAL_AbstractSensor

Then specify the hooks you are going to use in this sensor in the section HookEvents:

public function HookEvents()

The next and last part is where you should have the actual sensor code, i.e. the code that specifies how the event is fired. In this section, you should also specify the details about the event that is created in the WordPress activity log, including the severity, code / ID, text, and any other variables that you want to use in the text.

public function log_custom_event()

Save and name your sensor file

Once you are ready with the code, save the sensor file in your custom plugin’s directory. The filename should always be the same as that of the class without the WSAL_Sensors_prefix. So in this example, the filename is My_Custom_Sensor.php.

Declaring the events in WP Activity Log

Once you create your sensor file to trigger your unique Event ID, you need to declare what this ID means in terms of an alert. To do this, head to the custom-alerts file located in ‘/wsal-extension-example/wp-security-audit-log/custom-alerts.php’ .

Below is the sample code for three alerts with different severity:

$custom_alerts = array(
    __('Third Party Support', 'wp-security-audit-log') =>; array(
        __('Custom Alerts', 'wp-security-audit-log') =>; array(
            array(2222, E_CRITICAL, __('Custom critical Alert', 'wp-security-audit-log'), __('%CustomAlertText%', 'wp-security-audit-log')),
            array(3333, E_WARNING, __('Custom warning Alert', 'wp-security-audit-log'), __('%CustomAlertText%', 'wp-security-audit-log')),
            array(4444, E_NOTICE, __('Custom notice Alert', 'wp-security-audit-log'), __('%CustomAlertText%', 'wp-security-audit-log'))
        )
    )

Once the custom events have been declared and the code is ready, navigate to the Enable/Disable Alerts tab. You should be able to see your custom events in the Third Party Support tab, as seen in the below screenshot.

That’s it! Should you run into any issues, kindly get in touch with our team by opening a support ticket.

Register your custom event IDs with us

Have you created an extension that may be of use to others? If you create your own sensor and custom events, you can contact us and register your custom events, especially if you are creating events for a plugin or a component that is available to the public. By registering the events, you ensure they’re not used by anyone else, thus avoiding conflicts.