BugWP logo BugWP
Back to Community
Home / Community / Plugin → Activity log – monitor & record user changes

How to Log Custom Events with the Activity Log Plugin

20 threads Sep 16, 2025 Plugin → Activity log – monitor & record user changes

Content

Many WordPress administrators and developers use the Activity Log plugin to monitor changes on their sites. A common need is to extend this logging capability to track actions within custom plugins, themes, or specific scripts. This guide explains how you can leverage the plugin's built-in function to add your own custom log entries.

Why Log Custom Events?

The Activity Log plugin excels at tracking standard WordPress events like post updates, user management, and plugin installations. However, many sites run on custom code—unique admin actions, data import scripts, or specialized plugin functions. Tracking these activities is crucial for a complete audit trail, debugging, and understanding user actions beyond WordPress's core features.

The Solution: The aal_insert_log() Function

Based on discussions in the plugin's support forums, the primary method for adding custom logs is a function called aal_insert_log(). This function allows you to insert a record directly into the plugin's custom database table, automatically capturing details like the current user, timestamp, and IP address.

How to Use the Function

You can call aal_insert_log() anywhere in your custom plugin or theme's code, provided the Activity Log plugin is active. The function requires an array of parameters to define the log entry.

if ( function_exists( 'aal_insert_log' ) ) {
    $args = array(
        'action'         => 'updated', // The type of action (e.g., created, updated, deleted)
        'object_type'    => 'Custom Data', // The type of object being acted upon
        'object_subtype' => 'Daily Sync', // A more specific subtype (optional)
        'object_name'    => 'MySQL Data Correction', // A name or title for the object
        'object_id'      => 123, // The ID of the object (optional)
    );
    aal_insert_log( $args );
}

Parameter Breakdown:

  • action: A verb describing the event (e.g., 'exported', 'corrected', 'ran').
  • object_type: A general category for the event (e.g., 'Plugin', 'Theme Option', 'Stock Movement').
  • object_subtype: (Optional) A more specific sub-category.
  • object_name: A human-readable description of the specific event.
  • object_id: (Optional) The ID of the affected item, if applicable.

The function handles the user, IP address, and date automatically, so you only need to focus on describing the action itself.

Real-World Example: Logging a Data Correction

As mentioned in one support thread, a user had a custom script for correcting data in a MySQL table. They wanted to log each time a manual correction was made. Here is how they could implement it:

// This code runs when a data correction is performed
if ( function_exists( 'aal_insert_log' ) ) {
    aal_insert_log( array(
        'action'         => 'corrected',
        'object_type'    => 'Data Import',
        'object_subtype' => 'Manual Adjustment',
        'object_name'    => 'Adjusted product stock levels for ID #' . $product_id,
    ) );
}

Looking at the Plugin's Code for Reference

For developers who want to see how the plugin uses this function internally, the 'Activity Log – Monitor & Record User Changes' team often points to their own code as a reference. For instance, you can see how they log post updates in their GitHub repository within the class-aal-hook-posts.php file. This can provide valuable context for structuring your own log entries.

Important Considerations

  • Function Existence Check: Always wrap your call in if ( function_exists( 'aal_insert_log' ) ). This prevents fatal errors if the Activity Log plugin is ever deactivated.
  • Data Storage: The plugin stores all log entries in a custom database table, which is efficient and separate from the standard wp_posts table. This helps maintain site performance even as the log grows.
  • No Annotations: It is important to note that, as per other support threads, the plugin does not currently have a feature that allows users to manually add annotations or comments explaining why a change was made. The object_name parameter is your best tool for adding descriptive context.

By using the aal_insert_log() function, you can seamlessly integrate logging for your custom code, creating a unified and comprehensive activity history for your WordPress site.

Related Support Threads Support