Audit Trail#

The Audit Trail mode (HasAuditTrail) is AuditChain's flagship feature. It records every change to your Eloquent models in an immutable, cryptographically linked chain — making any tampering instantly detectable.

How It Differs from Activity Log#

While the Activity Log mode records the same events and data, the Audit Trail adds a SHA-256 hash chain. Each audit log entry contains:

• A hash computed from the audit data
• A prev_hash linking it to the previous entry

This creates an unbreakable chain where modifying any single entry invalidates every entry that follows.

The Hash Chain#

Entry #1: hash = SHA256(data + genesis_seed)
Entry #2: hash = SHA256(data + hash_of_entry_1)
Entry #3: hash = SHA256(data + hash_of_entry_2)
...

The data included in hash computation:

• auditable_type and auditable_id
• event (created, updated, deleted, etc.)
• user_id, ip_address, user_agent
• old_values and new_values
• personal_data_accessed
• timestamp
• prev_hash

Note: batch_uuid and context are intentionally excluded from hash computation. They are operational metadata — changing batch grouping or context should not invalidate the chain.

When to Use Audit Trail#

Use HasAuditTrail when you need:

• Tamper evidence — Prove that records haven't been altered
• Financial records — Transactions, invoices, payments
• Regulatory audits — Verifiable, unbroken audit history
• Regulatory compliance — GDPR, NIS2, SOX, HIPAA

Usage#

use GrayMatter\AuditChain\Concerns\HasAuditTrail;
use GrayMatter\AuditChain\Contracts\Auditable;

class Invoice extends Model implements Auditable
{
    use HasAuditTrail;
}

Verifying the Chain#

Run the verification command to check chain integrity:

php artisan audit:verify

Or use the programmatic API:

use GrayMatter\AuditChain\Services\AuditChainService;

$result = app(AuditChainService::class)->verifyChain();
// ['valid' => true, 'checked' => 150, 'errors' => []]

See Chain Verification for details on automated verification and notifications.