How to create custom events & IDs in the WordPress activity log

You are here:
Back to KB search

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

This document explains how you can build a sensor  and create custom alerts in WP Security Audit Log plugin to keep track of any type of change on your WordPress. Therefore now you can easily monitor changes on your WordPress that an out of the box installation of the plugin does not.

Using an MU-plugin to create custom events

The easiest way to create new activity log event IDs is to use a MU-Plugin (what is a Must Use Plugin?). To get started download the example MU-Plugin and use it as a base. It is fully commented and shows how to add custom events.

The MU-Plugin is made up of two parts:

  • a file called wp-security-audit-log-custom-events-loader.php
  • a folder that contains custom events and sensors.

Both the file and the folder should be uploaded inside the wp-content/mu-plugins/ directory. As soon as you upload these files they will be activated on your site.

Custom Events for Multisite

When you upload the plugin for custom activity log events and sensors in the wp-content/mu-plugin directory of a multisite network, the custom events will automatically enabled across the entire multisite network.

Introduction to the process of creating custom events

WP Security Audit Log sensors

For every set of changes, WP Security Audit Log has a sensor (what are the activity log sensors?). For example to monitor all the login and logouts on WordPress, the plugin’s sensor is 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 not familiar with events, first read the document What are WordPress activity log events. All the Events that the plugin uses in the WordPress activity log are declared in the file defaults.php which can be found in the root directory of the plugin (/wp-content/plugins/wp-security-audit-log). Refer to the complete list of WordPress activity log event IDs for more information about every event ID.

Custom events should be declared in a file called custom-alerts.php, which you can include in the mu-plugin. Otherwise you can filter in the location of the file using the wsal_custom_alerts_dirs filter and use the wsal_custom_sensors_classes_dirs to define the location that the sensors will be stored in.

The process of creating custom events and IDs

Therefore the process of creating a custom event, or a number of custom events in the WordPress audit trail is very simple:

  1. Create a sensor in the /wp-content/uploads/wp-security-audit-log/custom-sensors/ directory
  2. Declare the events in the file /wp-content/uploads/wp-security-audit-log/custom-alerts.php. As simple as that. Let’s start

Note: If you are using the mu-plugin then the paths above apply but if you are filtering in your own custom directory then substitute it in place of the directories you defined.

Read the rest of this post for more detailed explanation of how to build your sensor.

WP Security Audit Log sensors documentation and sample code

Before proceeding please download the example plugin which includes the sample sensor file and custom events file used for the below example.

Developing the sensor for WP Security Audit Log

Extract and open the sensor file CustomSensor.php from the zip file. The code in the sample sensor is fully documented  but just in case here is also a quick introduction. First you have to specify a class for your custom sensor:

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

In 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.

Save and name your sensor file

Once you are ready with the code save the sensor file in the /wp-content/mu-plugins/wp-security-audit-log/custom-sensors/ directory. The filename should always be the same as that of the class without the WSAL_Sensors_prefix. So in this example the file is CustomSensor.php.

Declaring the events in WP Security Audit Log

Once you create your sensor file, declare the events in the file custom-alerts.php which you can also find in the zip file you downloaded. The file should be saved in: /wp-content/mu-plugins/wp-security-audit-log/. Below is the sample code for 3 alerts with different severity:

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

Custom alerts in WP Security Audit Log

Register your custom events and IDs with us

If you create your own sensor and custom events we recommend you to 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 that it is not used by anyone else, hence avoiding conflicts.