Read Tracking#

Knowing who accessed sensitive data and when is fundamental to security auditing and incident response. AuditChain can log retrieved events whenever an auditable model is loaded from the database, giving you a complete access trail. This also supports compliance requirements such as GDPR Article 15 (right of access) and Article 33 (breach notification).

Enable Read Tracking#

Read tracking is off by default. Enable it in the config:

// config/audit-chain.php
'events' => [
    'log_reads' => true,
],

Once enabled, every Eloquent retrieved event on auditable models creates an audit log entry with event=retrieved.

What Gets Recorded#

A retrieved audit log captures:

• The model type and ID
• The authenticated user who triggered the query
• The IP address and user agent
• The timestamp
• Any active batch UUID and context

The old_values and new_values columns are empty for retrieved events — only the fact that the record was accessed is logged.

Personal Data Tracking#

If the model has personal data fields annotated, the personal_data_accessed column records which personal fields were present on the retrieved model. This is the key data point for GDPR breach impact assessments.

$user = User::find(42);
// Audit log: event=retrieved, personal_data_accessed=["email", "name"]

Volume Warning#

Read tracking is very verbose. A single page load that queries 50 users generates 50 audit log entries. Consider the impact before enabling:

• Storage: Audit log table growth will increase significantly
• Performance: Each retrieval triggers an insert (or queued job)
• Retention: Use audit:prune aggressively or set a short retention period for retrieved events

Selective Use#

If you only need read tracking on specific models, keep log_reads set to false globally and override getAuditableEvents() on the models that need it:

class Patient extends Model implements Auditable
{
    use HasAuditTrail;

    public function getAuditableEvents(): array
    {
        return ['created', 'updated', 'deleted', 'retrieved'];
    }
}

This way, only Patient models log retrieval events while other models behave normally.

When to Use#

• Healthcare applications — tracking who viewed patient records
• Financial services — logging access to account data
• GDPR breach response — determining which personal data was exposed
• Internal investigations — auditing who looked at sensitive records