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 event IDs in WP Activity 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.
Table of content
- Download the example activity log extension
- Introduction to the process of creating custom events
- WP Activity Log sensors documentation & sample code
- Register your custom events IDs with us
The example extension & download
We have an easy to use example plugin to get you started on the path to creating your own activity log extensions.
The plugin gives you everything you need to create your own events and is a great way to kick-start your development quickly. To begin, simply download the plugin (or clone via git if you prefer) and edit to suit your needs. The template is provided in a WordPress plugin format so will find common items such as the “plugin name”, “author” and so on are ready to be updated with your details also.
Once you have edited the files to your needs and are ready to begin coding your own events and sensors, simply head to the “wp-security-audit-log” directory and you will find an example custom-alerts.php as well as a template custom sensor to get you started. For details on how to create events, see “Introduction to the process of creating custom events” further down this article.
When working with the template, avoid making changes within the “core” directory. This is common code used across all of our extensions which may be updated in future.
Introduction to the process of creating custom events
WP Activity Log sensors
For every set of changes, WP Activity 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 activity log is very simple:
- Create a sensor in the /wp-content/uploads/wp-security-audit-log/custom-sensors/ directory
- 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.
What event IDs should you use?
When choosing event IDs for your events, it’s important to choose a unique event ID that we will never use, to ensure you don’t experience conflicts. We suggest you use event IDs starting at 1000000 (one million) – we do not plan of using more than 1,000,000 event IDs, so it is safe to use such event IDs.
Read the rest of this post for more detailed explanation of how to build your sensor.
WP Activity 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 Activity 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:
class WSAL_Sensors_CustomHooks extends WSAL_AbstractSensor
Then specify the hooks you are going to use in this sensor in the section HookEvents:
public function 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.
public function log_custom_event()
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 Activity 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:
$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 node. You should be able to see your custom events in the Third Party Support tab, as seen in the below screenshot.
Register your custom event 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.