146

Product support

Visit this product's website for support.

Categories

About

Easily view and manage audit logs for models within your OctoberCMS projects.

Installation

To install from the Marketplace, click on the "Add to Project" button and then select the project you wish to add it to before updating the project to pull in the plugin.

To install from the backend, go to Settings -> Updates & Plugins -> Install Plugins and then search for LukeTowers.EasyAudit.

To install from the repository, clone it into plugins/luketowers/easyaudit and then run composer update from your project root in order to pull in the dependencies.

To install it with Composer, run composer require luketowers/oc-easyaudit-plugin from your project root.

Contextual audit history

To get started using this plugin just add a few properties to the models that you wish to track:

class MyModel extends Model
{
    /**
     * @var array Behaviors implemented by this model class
     */
    public $implement = ['@LukeTowers.EasyAudit.Behaviors.TrackableModel'];

    /**
     * @var array The model events that are to be tracked as activities
     */
    public $trackableEvents = [
        'model.afterCreate' => ['name' => 'created', 'description' => 'The record was created'],
        'model.afterUpdate' => ['name' => 'updated', 'description' => 'The record was updated'],
        'model.afterDelete' => ['name' => 'archived', 'description' => 'The record was archived'],
    ];
}

Once you've added the TrackableModel behavior to a model, any local events fired on the model that have been set up in $trackableEvents will be automatically listened to and an audit record will be generated for each event.

In addition to the properties above, you can also add the following properties to model classes to configure the audit logging behavior:

class MyModel extends Model
{
    // ...

    /**
     * @var bool Flag to allow identical activities being logged on the same request. Defaults to false
     */
    protected $trackableAllowDuplicates = true;

    /**
     * @var bool Disable the IP address logging on this model (default from the luketowers.easyaudit.logIpAddress configuration value negated)
     */
    public $trackableDisableIpLogging = true;

    /**
     * @var bool Disable the User agent logging on this model (default from the luketowers.easyaudit.logUserAgent configuration value negated)
     */
    public $trackableDisableUserAgentLogging = true;
}

You can view a model's audit log by adding a field targeting the activities relationship (added by the TrackableModel behavior) with the type of activitylog to the relevant fields.yaml files:

activities:
    tab: Audit Log
    context: [update, preview]
    type: activitylog
    span: full

Advanced Usage

It is also possible to log events directly using the LukeTowers\EasyAudit\Classes\ActivityLogger class:

To use, create a new instance of this class and then either chain the methods for the data as required or call the log() method directly. Example (all in one):

$activity = new ActivityLogger();
$activity->log('updated', 'MyModel updated', $myModel, BackendAuth::getUser(), ['maintenanceMode' => true], 'MyVendor.MyPlugin');

Or (chained):

$activity = new ActivityLogger();
$activity->inLog('MyVendor.MyPlugin')
        ->for($myModel)
        ->by(BackendAuth::getUser())
        ->description('MyModel updated')
        ->properties(['maintenanceMode' => true])
        ->log('updated');

Additionally, the ActivityLogger() class is available on models implementing the LukeTowers.EasyAudit.Behaviors.TrackableModel behavior through the activity() method. This enables you to do the following:

class Asset extends Model
{
    // ...

    public function updateInventory()
    {
        // ...
        $this->activity('updated_inventory')->description("The asset's inventory was updated")->log();
    }
}
3.0.6

Fixed some bugs with filtering audit logs with large numbers of records

Nov 28, 2019

3.0.5

Detect when user impersonation is happening to log the original user instead of the impersonated one

Nov 28, 2019

3.0.4

Restrict system audit log page based on user permissions

Nov 28, 2019

3.0.3

Added the SystemActivities dashboard ReportWidget

Nov 28, 2019

3.0.2

Added the MyActivities dashboard ReportWidget

Nov 28, 2019

3.0.1

Added the ActivityLog FormWidget

Nov 28, 2019

3.0.0

Switched to paid license instead of MIT

Nov 28, 2019

2.2.0

Added IP address & user agent logging

Nov 28, 2019

2.1.1

Fixed "Call to member function is null"

Feb 11, 2019

2.1.0

Added a filterable system-wide audit log view

Feb 11, 2019

2.0.3

Fixed issues related to manually triggering events on models

Feb 11, 2019

2.0.2

Minor typo

Feb 11, 2019

2.0.1

Properly initialize for all supported model events - specifically model.afterCreate

Feb 11, 2019

2.0.0

Renamed plugin to EasyAudit

Dec 03, 2018

1.0.2

Retrieve source name from $activity->source_name allowing for modification by extending plugins

Dec 03, 2018

1.0.1

Initial version

Dec 03, 2018