README

Enterprise-grade audit logging for Craft CMS. Track every change, login, and system event — then send your logs anywhere.

$99.00 through the Craft Plugin Store for production use.

What It Does

Audit automatically logs actions performed by authenticated users:

• Content — Creating, saving, and deleting entries, assets, users, globals, and Commerce products/variants
• Users — Logins, logouts, account activation/deactivation, suspension, locking, group assignments
• Permissions — User and group permission changes
• Schema — Field, section, and entry type changes
• System — Plugin installs/uninstalls, route changes, database backups/restores, settings changes

No configuration required — install the plugin and logging starts immediately.

Requirements

• Craft CMS 5.5+
• PHP 8.2+

Installation

cd /path/to/project
composer require superbig/craft-audit

Then go to Settings → Plugins in the Control Panel and click Install for Audit.

Screenshots

Configuration

Create a config/audit.php file to customize behavior:

<?php

return [
    // How many days to keep log entries (default: 30)
    'pruneDays' => 30,

    // Master switch for logging
    'enabled' => true,

    // Toggle event categories
    'logElementEvents'       => true,
    'logChildElementEvents'  => false,
    'logDraftEvents'         => false,
    'logPluginEvents'        => true,
    'logUserEvents'          => true,
    'logRouteEvents'         => true,
    'logUserSecurityEvents'  => true,
    'logPermissionEvents'    => true,
    'logSchemaEvents'        => true,
    'logDatabaseEvents'      => true,

    // Auto-prune on admin CP requests
    'pruneRecordsOnAdminRequests' => false,

    // Geolocation (requires MaxMind license)
    'enabledGeolocation' => true,
    'maxmindAccountId'   => '',
    'maxmindLicenseKey'  => '',
    'dbPath'             => '',
];

This file supports multi-environment config, so you can have different settings per environment.

Event Categories

Console Commands

Prune Old Logs

Remove log entries older than pruneDays:

./craft audit/default/prune-logs

Update Geolocation Database

Download the latest MaxMind GeoLite2 database:

./craft audit/default/update-database

Geolocation

Audit can enrich log entries with geographic data using MaxMind GeoLite2 databases.

Setup

1. Create a free account at MaxMind.com
2. Generate a license key
3. Add your credentials to config/audit.php:

return [
    'enabledGeolocation' => true,
    'maxmindAccountId'   => getenv('MAXMIND_ACCOUNT_ID'),
    'maxmindLicenseKey'  => getenv('MAXMIND_LICENSE_KEY'),
];

1. Download the database:

./craft audit/default/update-database

Tracked Events

Here's the full list of events Audit captures:

Content Events

User Events

Permission Events

Schema Events

System Events

Extending Audit

Audit exposes events that let other plugins and modules hook into the logging pipeline. All events follow Craft's standard patterns — CancelableEvent for before hooks, Event for after hooks.

Events Reference

For full event class definitions and advanced usage, see docs/events.md.

Cancel Logging for Specific Conditions

Use EVENT_BEFORE_LOG to cancel or modify entries before they're saved:

use superbig\audit\services\AuditService;
use superbig\audit\events\BeforeLogEvent;

Event::on(
    AuditService::class,
    AuditService::EVENT_BEFORE_LOG,
    function(BeforeLogEvent $event) {
        // Skip audit for bot traffic
        if (str_contains($event->audit->userAgent ?? '', 'Googlebot')) {
            $event->isValid = false;
        }
    }
);

Register Custom Event Types

Let your plugin's events show up with proper labels in the Audit CP:

use superbig\audit\services\AuditService;
use superbig\audit\events\RegisterEventTypesEvent;

Event::on(
    AuditService::class,
    AuditService::EVENT_REGISTER_EVENT_TYPES,
    function(RegisterEventTypesEvent $event) {
        $event->eventTypes['order-completed'] = [
            'label' => 'Order completed',
            'category' => 'Commerce',
        ];
        $event->eventTypes['payment-received'] = [
            'label' => 'Payment received',
            'category' => 'Commerce',
        ];
    }
);

Filter by Element Type

Use EVENT_DEFINE_SHOULD_LOG for cheap, early filtering — before the audit model is even built:

use superbig\audit\services\AuditService;
use superbig\audit\events\ShouldLogEvent;

Event::on(
    AuditService::class,
    AuditService::EVENT_DEFINE_SHOULD_LOG,
    function(ShouldLogEvent $event) {
        // Never log Asset saves
        if ($event->element instanceof \craft\elements\Asset) {
            $event->shouldLog = false;
        }
    }
);

Modifying Snapshots

Use EVENT_SNAPSHOT to add custom data to audit log snapshots:

use superbig\audit\services\AuditService;
use superbig\audit\events\SnapshotEvent;

Event::on(
    AuditService::class,
    AuditService::EVENT_SNAPSHOT,
    function(SnapshotEvent $event) {
        $event->snapshot['customField'] = 'custom value';
    }
);

Permissions

Audit registers two permissions you can assign to user groups:

Template Variables

Access audit data in your Twig templates:

{# Get events for a specific element #}
{% set events = craft.audit.getEventsForElement(entry) %}

{# Loop through events #}
{% for event in events %}
    {{ event.event }} by {{ event.user }} at {{ event.dateCreated|date }}
{% endfor %}

Upgrading

From Craft 4 (Audit 2.x/3.x) to Craft 5

• PHP 8.2+ is now required
• Run composer update superbig/craft-audit after upgrading Craft
• All existing audit data is preserved — no migration needed
• Event naming is more semantic in v5 (e.g., entry-created for entries vs. generic created-element)

Support

• GitHub Issues
• Craft Plugin Store

Credits

• Auditing icon by Ralf Schmitzer

Brought to you by Superbig