Verifiable Audit Logging with Laravel Chronicle

Audit logs are only useful if you can trust them. A database table full of activity records is easy to query, but it's equally easy to quietly edit or delete a row — and there's nothing in a typical Laravel audit package to tell you that happened.

Laravel Chronicle by Vasileios Ntoufoudis approaches this differently. Rather than just writing rows to a table, it builds a cryptographic hash chain across every entry using SHA-256. Each new record incorporates a hash of the previous one, so the entire ledger is interconnected. Alter or remove any entry, and the chain breaks and Chronicle will tell you.

Getting Started

composer require laravel-chronicle/core
php artisan chronicle:install

Writing to the Ledger

Use the record() method on the Chronicle facade to write a new entry into the ledger:

use Chronicle\Facades\Chronicle;

Chronicle::record()
    ->actor($reviewer)
    ->action('application.approved')
    ->subject($application)
    ->metadata(['from' => 'pending', 'to' => 'approved'])
    ->tags(['applications', 'workflow'])
    ->commit();

Every entry needs an actor, an action, and a subject. The metadata and tags fields let you attach whatever context makes sense for your domain.

Querying Entries

Chronicle provides scopes for the most common lookups — by actor, subject, action, or tag:

use Chronicle\Entry\Entry;

Entry::forActor($reviewer);
Entry::forSubject($application);
Entry::action('application.approved');
Entry::withTag('workflow');

For larger ledgers, Chronicle supports streaming entries one at a time using a database cursor, so memory usage stays constant no matter how many entries there are. cursorPaginateLedger() handles paginated browsing without loading the whole table.

Proving the Ledger Hasn't Changed

Beyond the hash chain, Chronicle also lets you anchor the ledger's state at a point in time with a signed checkpoint. At minimum, a checkpoint stores the current chain head, the signing algorithm, a cryptographic signature, and a timestamp. If someone later claims the log was clean at a given date, you have a verifiable snapshot to back that up.

For situations where the audit data needs to leave your system entirely — handing off to an external auditor, or storing a copy offsite — Chronicle can export the ledger as a signed, self-contained dataset:

php artisan chronicle:export

The export produces three files — entries.ndjson, manifest.json, and signature.json — which can be verified independently by anyone with the package using the following artisan command:

php artisan chronicle:verify-export

Chronicle is a good fit for applications that require reliable audit trails — compliance workflows, financial records, security logging, or forensic analysis. You can find the source and full documentation on GitHub.