Activity Logs Plugin

The Activity Logs plugin provides comprehensive activity tracking and logging functionality for your application. It automatically logs various system events including authentication, requests, responses, exceptions, and custom activities. All logs are processed asynchronously through a queue system for optimal performance.

Features

Automatic Activity Tracking

The plugin automatically tracks various system events:

  • Authentication events: Sign in, sign out, sign in errors
  • Request and response logging: One record before each plugin method call (action request) and one record for each response (action response)
  • Exception and error tracking: Captures exceptions and errors
  • Data Grid Store (DGS) operations: Tracks DGS-related activities

Activity Categories

Activities are organized into the following categories:

  • General activities: General system activities
  • Authentication events: User authentication-related events
  • Exceptions and errors: System exceptions and errors
  • DGS operations: Data Grid Store operations

Activity Types

Each activity can be classified by type:

  • Success events: Successful operations
  • Error events: Failed operations or errors
  • Loading events: Operations in progress

Priority Levels

Activities can be assigned priority levels:

  • Low priority: Non-critical activities
  • Medium priority: Standard activities
  • High priority: Critical activities requiring attention

Automatic Data Collection

The plugin automatically collects the following data for each activity:

  • User ID: Automatically captured if user is authenticated
  • IP address: Client IP address
  • User agent: Browser/client user agent string
  • Current URL: The URL where the activity occurred
  • Timestamp: Automatic timestamp of when the activity occurred

Asynchronous Processing

  • Queue-based logging: All logs are processed through a queue system for optimal performance
  • Non-blocking activity recording: Activity recording doesn't block the main application flow

Management Interface

  • View and filter activity logs: Browse and search through all activity logs
  • Accessible at: /manage/activity/logs/

Requirements

  • A Festi project with the Jimbo system plugin. The plugin listens to the Jimbo sign-in, sign-out and exception events.
  • The Queues plugin. The plugin adds each record to the queue ActivityLogs.
  • The Festi Theme package (Festi\Theme\Plugin\DisplayPlugin).
  • A MySQL or PostgreSQL database. The install folder has no file for MSSQL.

Installation

Use the Festi CLI to install the plugin. Run the command from the project root:

./vendor/bin/festi-plugin --mode install --path ./src/dashboard/ --dump ./dumps/ \
    --plugin ActivityLogs --repository [email protected]:FestiPlugins/PHP_Festi_Plugin_Activity_Logs.git

This example was not run for this page.

The command adds the repository to the plugins directory as a git submodule. It copies install/install.<database type>.sql into the dumps directory as a new migration and applies it. The migration creates the tables activity_logs and queue_activitylogs. It also adds the plugin, the URL rule /manage/activity/logs/ for the area backend, the section activity_logs_list and the menu item Activity Logs.

Commit the submodule and the new migration together.

Configuration

Queue worker

The plugin does not write a record to activity_logs during the request. A queue worker writes the records. Add a cron job for the worker of the Queues plugin:

*/5 * * * * /usr/bin/php -q PATH_PLUGINS/Queues/queues.php --id WORKER_ID --name ActivityLogs

Refer to the Queues plugin for the worker parameters.

Permissions

The page /manage/activity/logs/ uses the section activity_logs_list. The install file does not give this section to a user type. Give the permission to the necessary user types, for example on the ACL Manager page /manage/acl/.

Cron scripts

The plugin does not record DGS operations when the constant IS_CRON is true.

Usage

Creating Custom Activity Logs

To create custom activity logs in your code, use the plugin's facade:

<?php

use plugin\ActivityLogs\domain\model\ActivityLogValuesObject;

$activityLogsPlugin = Core::getInstance()->getPluginInstance('ActivityLogs');

$activityLogValuesObject = new ActivityLogValuesObject();
$activityLogValuesObject->setCategory(ActivityLogValuesObject::CATEGORY_GENERAL);
$activityLogValuesObject->setAction('custom_action');
$activityLogValuesObject->setType(ActivityLogValuesObject::TYPE_SUCCESS);
$activityLogValuesObject->setPriority(ActivityLogValuesObject::PRIORITY_MEDIUM);
$activityLogValuesObject->setNote('Custom activity description');
$activityLogValuesObject->setContext(json_encode(['additional' => 'data']));

$activityLogsPlugin->createQueue($activityLogValuesObject);

Available Categories

ActivityLogValuesObject::CATEGORY_GENERAL        // General activities
ActivityLogValuesObject::CATEGORY_AUTHENTICATION // Authentication events
ActivityLogValuesObject::CATEGORY_EXCEPTION      // Exceptions and errors
ActivityLogValuesObject::CATEGORY_DGS            // Data Grid Store operations

Available Types

ActivityLogValuesObject::TYPE_SUCCESS  // Successful operations
ActivityLogValuesObject::TYPE_ERROR    // Error events
ActivityLogValuesObject::TYPE_LOADING  // Loading/processing events

Available Priorities

ActivityLogValuesObject::PRIORITY_LOW    // Low priority events
ActivityLogValuesObject::PRIORITY_MEDIUM // Medium priority events
ActivityLogValuesObject::PRIORITY_HIGH  // High priority events

Activity Log Fields

The following fields are available for activity logs:

  • id_user - User ID (automatically set if user is authenticated)
  • type - Activity type (success, error, loading)
  • category - Activity category (general, authentication, exception, dgs)
  • priority - Priority level (low, medium, high)
  • action - Action identifier
  • cdate - Creation date (automatically set)
  • url - Current URL (automatically set)
  • ip - IP address (automatically set)
  • note - Additional notes or description
  • context - JSON-encoded context data
  • useragent - User agent string (automatically set)

Management Interface

Access the activity logs management interface at:

/manage/activity/logs/

This interface allows you to: - View all activity logs - Filter logs by various criteria - Search through activity history - Review system activity patterns

Events

BeforeLoadActivityLogsEvent

The plugin dispatches this event before the activity logs store loads its values. Use this event to change the store, for example to set filters.

Add the event listener in the init.php file of your plugin:

<?php

use plugin\ActivityLogs\domain\event\BeforeLoadActivityLogsEvent;

$this->addEventListener(
    BeforeLoadActivityLogsEvent::TYPE,
    function (BeforeLoadActivityLogsEvent &$event) {
        $store = $event->getStore();

        $filters = &$store->getModel()->getFilters();
        $filters['your_filter_name'] = $yourFilterValue;
    }
);

BeforeCreateQueueEvent

This event is dispatched before an activity log is added to the queue, allowing you to modify the activity log data before it's processed.

<?php

use plugin\ActivityLogs\ActivityLogsPlugin;
use plugin\ActivityLogs\domain\event\BeforeCreateQueueEvent;

$this->addEventListener(
    ActivityLogsPlugin::EVENT_BEFORE_CREATE_QUEUE,
    function (BeforeCreateQueueEvent &$event) {
        $activityLogValuesObject = $event->getActivityLogValuesObject();

        // Modify the activity log before it's queued
        $activityLogValuesObject->setNote('Modified note');
    }
);