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 (actionresponse) - 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
installfolder 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 identifiercdate- Creation date (automatically set)url- Current URL (automatically set)ip- IP address (automatically set)note- Additional notes or descriptioncontext- JSON-encoded context datauseragent- 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');
}
);