README

This plugin implements an "audit trail" for any of your Table classes in your application, that is, the ability of recording any creation, modification or delete of the entities of any particular table.

By default, this plugin stores audit logs in a database table using the CakePHP ORM. The plugin also includes:

• Built-in UI for browsing and searching audit logs
• Real-time monitoring and alerting system
• Configurable retention policies with automated cleanup
• Optional Elasticsearch support for high-volume applications

Installation

Install via composer:

composer require dereuromark/cakephp-audit-stash
bin/cake plugin load AuditStash

Run the migrations to create the audit_logs table:

bin/cake migrations migrate -p AuditStash

Quick Start

Enable audit logging in any Table class by adding the behavior:

class ArticlesTable extends Table
{
    public function initialize(array $config): void
    {
        parent::initialize($config);
        $this->addBehavior('AuditStash.AuditLog');
    }
}

Optionally, track the current user and request info in AppController:

use AuditStash\Meta\RequestMetadata;
use Cake\Event\EventManager;

public function beforeFilter(EventInterface $event)
{
    parent::beforeFilter($event);

    EventManager::instance()->on(
        new RequestMetadata(
            request: $this->getRequest(),
            user: $this->getRequest()->getAttribute('identity')?->getIdentifier(),
        ),
    );
}

That's it! Your application is now tracking all creates, updates, and deletes.

Features

Audit Log Viewer

Browse and search audit logs through a built-in web interface at /admin/audit-logs:

• Filter by table, user, event type, date range, transaction ID
• View detailed before/after comparisons with inline or side-by-side diff
• Timeline view showing complete history for specific records
• Export to CSV or JSON

See Viewer Documentation for details.

Monitoring & Alerting

Real-time monitoring system that detects suspicious activities:

• Mass deletion detection
• Off-hours activity monitoring
• Customizable rules and notification channels (email, webhook, logs)
• Extensible architecture for custom rules

See Monitoring Documentation for setup.

Log Retention & Cleanup

Automated cleanup with configurable retention policies:

• Table-specific retention periods
• Command-line tool for manual or automated cleanup
• Cron-friendly with dry-run support

See Retention Documentation for configuration.

Flexible Storage

• Database (default): Simple, fast, works out-of-the-box
• Elasticsearch: Optional for high-volume applications
• Custom: Implement your own persister

See Configuration Documentation for storage options.

Documentation

• Configuration - Database and Elasticsearch setup, persister options
• Usage - Behavior configuration, metadata tracking, custom persisters
• Viewer - Web UI for browsing and searching audit logs
• Retention - Automated log cleanup and retention policies
• Monitoring - Real-time alerting for suspicious activities

Demo

https://sandbox.dereuromark.de/sandbox/audit-stash

Testing

Run the test suite:

vendor/bin/phpunit

For Elasticsearch tests, set the environment variable:

elastic_dsn="Cake\ElasticSearch\Datasource\Connection://127.0.0.1:9200?driver=Cake\ElasticSearch\Datasource\Connection" vendor/bin/phpunit