Download the PHP package graymatter/laravel-audit-chain without Composer

Laravel Audit Chain

An immutable audit trail for Laravel Eloquent models with optional cryptographic hash chain verification. Built for GDPR (articles 15, 17, 33) and NIS2 (article 21) compliance.

Features

• Two modes: Light activity log (HasActivityLog) or full cryptographic hash chain (HasAuditTrail)
• Immutable audit logs: Eloquent guards prevent updates/deletes on audit records
• Cryptographic hash chain: SHA-256 linked chain for tamper detection (full mode)
• GDPR compliance: Personal data annotation, anonymization, full subject data export
• SoftDeletes support: Auto-detects SoftDeletes, captures restored and forceDeleted events
• Custom events: Record business events via $model->audit('published')
• Batch grouping: Group related audit logs under a single UUID via AuditChain::batch()
• Free-form metadata: Attach context to audit logs via AuditChain::context()
• Disable logging: AuditChain::withoutAudit() for seeds, imports, and migrations
• Field control: $auditInclude / $auditExclude + auto-exclusion of $hidden fields
• User agent logging: Captures browser/client user agent automatically
• READ event capture: Opt-in retrieved event logging
• Chain verification: audit:verify command with --notify for cron scheduling
• Log pruning: audit:prune command with configurable retention
• Notifications: Mail + webhook alerts (Slack, Teams, Discord compatible)
• Separate DB connection: Isolate audit data from application data
• Queue support: Offload audit recording to background jobs

Requirements

• PHP >= 8.2
• Laravel 11 or 12

Installation

Publish the config and migration:

Usage

Mode 1: Activity Log (Light)

Simple activity logging without hash chains. Audit logs have hash and prev_hash set to null.

Mode 2: Audit Trail (Full)

Cryptographic hash chain for immutable, verifiable audit logs.

Custom Events

Record business-level events via the audit() method:

Batch Grouping

Group related operations under a single batch UUID:

Free-Form Context

Attach metadata to all subsequent audit logs:

Disable Logging

Suppress audit logging for seeds, imports, or maintenance:

SoftDeletes

SoftDeletes is auto-detected. When present, restored and forceDeleted events are automatically captured in addition to standard CRUD events.

PersonalData Attribute

Annotate model properties as personal data using the PHP 8 attribute:

Or use the $personalData array:

Field Control

Control which fields are audited:

Fields in the model's $hidden array (passwords, tokens, etc.) are automatically excluded from audit values.

Accessing Audit Logs

GDPR

Data Export (Article 15)

Full Subject Access (Article 15)

Export personal data and the complete audit trail in one call:

The audit trail includes event, old/new values, personal data accessed, IP address, user agent, batch UUID, context, and timestamps — but excludes internal chain fields (hash, prev_hash).

Anonymization (Article 17)

Uses saveQuietly() internally to avoid triggering audit events during anonymization. The model's primary key is appended to avoid UNIQUE constraint violations when anonymizing multiple records.

Read Tracking

Opt-in via config to capture retrieved events (Article 15 / Article 33 — who accessed personal data):

Chain Verification

Artisan Command

Log Pruning

Automated Scheduling (Cron)

Schedule verification and pruning in your routes/console.php:

Notifications

When --notify is used and verification fails, notifications are sent based on config:

Webhook payloads are compatible with Slack, Microsoft Teams, Discord, and custom endpoints. Both text and content keys are included for cross-platform compatibility.

Programmatic API

Configuration

Security

Chain Seed

Set AUDIT_CHAIN_SEED in your .env to a random, secret value. The seed is used to compute the genesis hash — the first link in the chain. A predictable genesis hash weakens tamper-evidence guarantees.

Database User Permissions

For maximum immutability, use a dedicated database user for the audit connection with INSERT and SELECT only — no UPDATE or DELETE. Eloquent guards prevent modification at the application layer, but DB-level restrictions ensure immutability even if the application is compromised.

Timestamps

All audit timestamps are stored in UTC via now()->utc()->toDateTimeString() to ensure consistent hash computation across time zones.

Eloquent Immutability

The AuditLog model throws RuntimeException on updating and deleting events, preventing modification through Eloquent. The $fillable whitelist further restricts which attributes can be set.

Testing

Full quality checks (Pint + Rector + PHPStan + Pest):

Licensing

This package is dual-licensed:

• MIT License — for open source and non-commercial use
• Commercial License — required for proprietary/commercial use

See LICENSE_COMMERCIAL for details.