Reference Omeka Classic plugin

Logging from Other Plugins

Other plugins log their own events to Audit Trail with one Omeka Classic plugin hook, audit_trail_log. When Audit Trail is not installed or not active, the hook has no listener and nothing happens, so a plugin can fire it without checking.

The hook

fire_plugin_hook('audit_trail_log', [
    'action'        => 'theme_file.save',  // "<type>.<verb>", lowercase
    'resource_type' => 'theme_file',       // short type name
    'resource_id'   => null,               // int or null
    'detail'        => 'Saved themes/plinth/items/show.php',  // one human-readable line
    'data'          => ['bytes' => 5120],  // optional array, stored as JSON
]);
Argument Required
action yes Lowercase type.verb, made of letters, digits, _ and -, at most 128 characters: theme_file.save, version.restore, oral_history.publish. Anything else is not logged (and a line goes to the PHP error log).
resource_type no A short type name, lowercase with underscores. Default: the part of the action before the first dot. It fills the log's Resource type filter.
resource_id no An integer (or a short string), or null.
detail no One line that says what happened, shown under the record in the log. Tags are stripped and whitespace collapsed; at most 1,024 characters.
data no An array (or object), stored as JSON and shown on the entry's page and in exports. Keep it small: above 60 KB only an excerpt is kept.
resource_label no The record's name, shown in the log's Resource column.
resource_url no Its admin page, relative to the admin (items/show/12, theme-file-editor?theme=plinth) or a full address.

Audit Trail adds the rest itself: the time, the signed-in user (or System in jobs and scripts), the source (web, REST API, background job, command line), the batch, the IP address and the user agent. It never throws: a problem with the log is reported to PHP's error log and the plugin's request carries on.

The events go under Events reported by other plugins in the settings; when that box is not ticked, or logging is off, the hook does nothing.

Examples

A theme file editor saving a file:

fire_plugin_hook('audit_trail_log', [
    'action' => 'theme_file.save',
    'resource_type' => 'theme_file',
    'detail' => sprintf('Saved themes/%s/%s', $theme, $path),
    'data' => ['theme' => $theme, 'path' => $path, 'bytes' => strlen($contents)],
]);

A versioning plugin restoring an item:

fire_plugin_hook('audit_trail_log', [
    'action' => 'item.restore',
    'resource_type' => 'item',
    'resource_id' => $item->id,
    'resource_label' => metadata($item, 'display_title', ['no_escape' => true]),
    'resource_url' => 'items/show/' . $item->id,
    'detail' => sprintf('Restored item #%d to version %d', $item->id, $version),
    'data' => ['version' => $version],
]);

From the command line, bin/log-event.php fires the same hook (see CLI Scripts).

Good practice

  • Name actions after what happened to what: <type>.<verb>, with the verb in the base form (save, restore, publish). Use the core types (item, collection, file…) when the event is about one of those records, so it appears in its history.
  • Never put secrets in detail or data: passwords, API keys, tokens. The log is exported and kept for a long time.
  • Log what a person did, once: one event per action, not one per internal step. A job that changes many records shares one batch on its own.
  • Records your plugin saves through Omeka (its own models) can be logged automatically instead, with the filter below.

Logging a plugin's own records automatically

A plugin whose records extend Omeka_Record_AbstractRecord can ask Audit Trail to log their creates, updates and deletes from the record hooks, as it does for items, with the audit_trail_record_types filter:

public function filterAuditTrailRecordTypes($types)
{
    $types['BlogPost'] = [
        'type' => 'blog_post',              // resource type in the log
        'group' => 'blog',                  // the settings box that turns it on and off
        'group_label' => 'Blog posts',      // that box's label
        'label' => 'title',                 // property naming a record
        'url' => 'blog/posts/edit/%d',      // its admin page; %d is the ID
        'tracked' => ['title', 'slug', 'is_published'],  // compared on update
    ];
    return $types;
}
Key
type Required. The resource type. Actions become blog_post.create, blog_post.update, blog_post.delete.
group The event group (settings box). Default: the type with an s.
group_label The box's label. Default: the type in words.
label The property that names a record. Default: title, name or label, whichever the record has.
url The admin page, relative to the admin, with %d for the ID.
tracked Columns compared with the stored row on update; the entry lists those that changed.
quiet true to log an update only when a tracked column changed.
skip Operations not to log, for example ['update'].

Remember to add 'audit_trail_record_types' to your plugin's $_filters. The new group is ticked when the plugin's settings have every box ticked (the default).

Log in for Support