Extend Activity Log With Custom Events

Starting with Shield v16.0 it's possible to augment Shield's Activity Log with your own custom events.

Note:

  • This is a ShieldPRO feature.
  • This requires help from a proficient PHP developer, familiar with WordPress development.
  • Customer Support: We can help with any errors that occur as a direct result of your implementation that pertains to directly to Shield functionality. Support will not help you debug your custom PHP code and implementation. Again, please ensure the developer has sufficient experience with WordPress & PHP and reads this document fully.  Any bugs that are discovered with Shield should be reported in the normal bug reporting manner with full details, error logs, and steps to reproduce the bug.

What Are Custom Activity Logs?

Shield uses an "events" system to track activity on the site and create logs in the Activity Log. The events system is also used to capture offenses and other related subsystems in the plugin.

By extending this system, you're essentially adding your own custom "events" that Shield will process alongside its own built-in events.

The custom events that you supply must adhere to certain rules and can be used to write logs to the Activity Log, and even register offenses against IP addresses for particular actions taken on your site that you deem to be worthy of offenses.

Important: due care must be taken when defining events as being "offensive" as you may inadvertently block legitimate visitors.

How Can You Extend The Events System?

We've provided a WordPress filter that you can use to supply definitions for your custom events. Again, you must adhere to the data structure required by the plugin for all custom events or your entire set of events will be discarded.

Step 1 - Create A Custom Event Definition

Filter name: shield/events/custom_definitions
Parameters:

  1. array $events

The following is an example of how you might add your own custom event.

Important Points To Note:

Timing

The addition of the WordPress filter must be before the event is fired and should only be added once.

Event Key (custom_hello_world_event from this example)

  1. Must be a string (integers not supported)
  2. Must begin with "custom_"
  3. Max length 50 characters
  4. May only contain letters a-z and underscore (_)

Strings

  1. The strings array must contain 'name' which must be a non-empty string.
    The name is used in the Activity Log to help filter events.
  2. The strings array must contain 'audit' which must be a non-empty array of strings.
    The audit text is used in the Activity Log to offer details about the event.

Offense

The offense value must be true or false. If you set this to true, an offense will be registered against an IP address every time it is fired.

Step 2 - Fire Your Custom Event

You first need to decide when and where you want to fire your custom event. You need to think carefully about this and ensure that you surround the event firing with all the necessary conditions.

To fire your custom event, simply use the code below:

shield_fire_event( $event_name );

e.g. using the example above: shield_fire_event( 'custom_hello_world_event' );

Event Fire Example:

You could put this code in your functions.php. And assuming you have all the necessary code on your site, and in the correct place, you can simply call https://mysite.com/?test_my_event=1 and it will fire the event.

Future Development Plans

Shield's event logging system support the ability to add parameters to events so that they may also appear in the activity log. We have not provided support for parameters for custom event as-yet, though it is in there. If a developer wishes to investigate Shield code in order to discover how this is achieved, they may do so. For now, this is currently an undocumented feature and may change in the future.