Reference Omeka Classic plugin

CLI Scripts

Two scripts in plugins/AuditTrail/bin/ work from the command line: one purges old entries (for cron), the other adds an entry (for deployment and maintenance scripts). Both start Omeka Classic themselves and need no web server or job queue.

Run them from your Omeka folder, as a user that can read db.ini. They find the installation from the path you type (plugins/AuditTrail/bin/…, three folders up from bin/), which also works when the plugin folder is a link shared by several sites. Elsewhere, give the installation with --omeka=/path/to/omeka.

purge-audit-log.php

Deletes the entries older than the retention period. See Purging Old Entries for scheduling it.

php plugins/AuditTrail/bin/purge-audit-log.php [--days N] [--dry-run] [--quiet] [--omeka=/path/to/omeka]
Option Description
--days N Use N days instead of the Retention period setting. Must be a positive whole number. Also purges while logging is turned off.
--dry-run Print how many entries would be deleted, and delete nothing.
--quiet No output except errors.
--omeka=… The Omeka installation, when it is not the one the script is in.
--help Print the usage and exit.

What it does:

  1. Takes the retention period from --days or the setting.
  2. If it is 0, prints Retention is 0 (keep entries forever): nothing to purge and stops.
  3. If logging is turned off and --days was not given, prints Logging is turned off; purge skipped and stops.
  4. Deletes the entries older than the cutoff (now minus the period, in UTC), a thousand at a time, until none are left.
  5. Logs the purge (audit_trail.purge, actor System, source Command line) when it deleted entries, and prints the count.
[AuditTrail] Purging entries older than 2025-10-27 02:00:00 UTC (365 days).
[AuditTrail] Purge complete: 1284 entries deleted.

[AuditTrail] [DRY RUN] Purging entries older than 2025-10-27 02:00:00 UTC (365 days).
[AuditTrail] Dry run: 1284 entries would be deleted.
Exit status Meaning
0 Success, or nothing to do
1 Omeka or the plugin could not be found or started, or the database failed
2 Invalid arguments (for example --days 0)

The same purge runs as the background job AuditTrail_Job_Purge from the Run purge now button, and once a day by itself when Purge automatically is on.

log-event.php

Adds an entry through the same audit_trail_log hook other plugins use (see Logging from Other Plugins). Use it to record what scripts do to the site, such as a deployment, a restore or a bulk fix made outside Omeka.

php plugins/AuditTrail/bin/log-event.php --action=<type.verb> [--type=…] [--id=…] [--detail="…"] \
    [--data='<JSON>'] [--user=<user ID or username>] [--omeka=/path/to/omeka]
Option Description
--action Required. Lowercase type.verb, for example site.maintenance or deployment.finish.
--type The resource type. Default: the part of the action before the dot.
--id The resource ID.
--detail One line saying what happened.
--data A JSON object or array, stored as the entry's data.
--user The actor: a user ID or username. Default: System.

Values can follow = or a space: --detail "Restored the files".

php plugins/AuditTrail/bin/log-event.php --action=site.maintenance \
    --detail="Restored the files from last night's backup" --data='{"ticket": 42}'
Logged entry #1284.
Exit status Meaning
0 Logged; the entry's ID is printed
1 Not logged: logging is off or Events reported by other plugins is not ticked; or Omeka could not be started
2 Invalid arguments
Log in for Support