Event-driven audit logging of user activity for Laravel. Records who did what, to what, on whose behalf and from where, as append-only database rows behind a storage contract, so a custom store can take the place of the database.

Captures Laravel's own authentication events on its own, and gives the application one call to record anything else - an invoice approved, a user suspended, a setting changed. Stands alone: it names no other package, and exposes a mapping seam that suite packages and applications register their own events through.

Status: in development. The API and schema below describe the planned 1.0 and may change before it is tagged.

Core Concept

Features

• Automatic capture of Laravel's authentication events: sign-in, failed sign-in, remember-me restore, sign-out, lockout, registration, verification and password reset - one row each, and none per request.
• Gate denials, once turned on: one row per denied check, with the ability, and its arguments only as model references, class names or a marker, never their values.
• Model changes: watch a model's creation, update, deletion, restore and force delete, keeping only the fields named, written once its transaction commits.
• Bulk operations: one entry for an operation on many subjects, with a signed, encrypted manifest of every subject, refused rather than truncated when it is too large.
• Manual capture through AuditLog::record() and a fluent builder, filled in with the actor, guard, IP address, user agent, origin and request id.
• Mapping seam: register a mapper for any event class or interface and record it with AuditLog::capture().
• Transaction-safe writes: a record made inside a transaction is written once it commits, and dropped if it rolls back, unless it is written immediately or fail-closed.
• Never silently lost: a failed write is reported, dispatched as an event and spilled to a log channel, without breaking the request - or thrown, when the record must exist.
• Redaction of secret-shaped keys, keyed hashing of sign-in identifiers, IP address minimisation and size caps.
• Chained membership seals: entries are sealed in signed batches, each chained to the one before it and optionally anchored on a write-once disk, and audit-log:verify reports any entry or seal changed, removed or added.
• Append-only storage with indexed actor, subject, principal and tenant columns, portable across SQLite, MySQL and PostgreSQL, and retention through Laravel's model:prune.
• Reading the trail by actor, subject, principal or tenant, with cursor pagination and translatable descriptions.
• Request and job context: the request id and actor follow a request into the jobs it dispatches, and nothing leaks between Octane requests or queued jobs.
• Testing fake with assertions for what was, and was not, recorded.

Installation

composer require sinemacula/laravel-audit-log

Configuration

Publish the config and the migrations, and migrate:

php artisan vendor:publish --tag=audit-log-config
php artisan vendor:publish --tag=audit-log-migrations
php artisan migrate

The package schedules audit-log:seal every five minutes, and audit-log:seal --sweep and audit-log:verify --strict --sweep-first daily, on Laravel's scheduler, each in the background, kept from overlapping itself and, on a cache store every server shares, run on one server. Set a run's schedule to null to schedule nothing and run that command elsewhere. audit-log:verify exits non-zero on a tampered, incomplete or unverifiable seal, and with --strict also on one the anchor does not confirm.

Run php artisan audit-log:check in a deploy pipeline: it reports every malformed setting, missing connection, schema problem and unusable key at once, exits non-zero on any, and writes nothing. It also says whether the spill channel is the one a replay can read, and fails on one that would fail together with the store.

Usage

Record an action, with the ambient actor, guard, client and request filled in:

use SineMacula\Laravel\AuditLog\Facades\AuditLog;

AuditLog::record('invoice.approved', subject: $invoice, properties: ['amount' => '1200.00']);

Or build one up:

use SineMacula\Laravel\AuditLog\Facades\AuditLog;

AuditLog::event('user.suspended')
    ->on($user)
    ->by($admin)
    ->forTenant($organisation)
    ->withProperties(['until' => $until])
    ->record();

A record made before the auth middleware has run has no actor, because the package only reads a user the guard already holds and never loads one; name it with ->by(). A request id or traceparent sent by the edge is believed only with its flag on and from a proxy TrustProxies trusts, and that proxy must overwrite or validate those headers, because only the immediate peer is checked.

Record a completed disclosure, with its purpose and channel as machine-readable codes:

AuditLog::accessed('document.downloaded', subject: $document, purpose: 'legal_hold', channel: 'portal')->record();

Choose when a record is written. Inside a transaction a record waits for the commit, and is dropped on a rollback:

AuditLog::event('invoice.approved')->on($invoice)->afterCommit()->record();          // the default
AuditLog::event('invoice.approved')->on($invoice)->afterCommit('billing')->record(); // that connection's transaction
AuditLog::event('invoice.approved')->on($invoice)->immediately()->record();          // now, whatever is open
AuditLog::event('invoice.approved')->on($invoice)->transactional()->record();        // atomic with an open transaction
AuditLog::event('invoice.approved')->on($invoice)->failClosed()->record();           // now, and a failure must throw

A failClosed() record needs a durable store and a transactional() record a store that joins the transaction, unless the outbox acknowledges for it.

A failed write does not break the request by default: the record is spilled to failure.log_channel as one line, the failure is reported without any value of the record, AuditWriteFailed is dispatched, and the code carries on. With failure.mode set to throw, or for a failClosed() record, the record is spilled and the failure is thrown. A transactional() record always throws and is never spilled, because it describes work that has not committed. Either way the failure thrown holds the record's id and code, and none of its values. Replay the spilled lines once the store is back:

php artisan audit-log:replay --spill=storage/logs/audit-spill.log

To write a record in the application's own transaction and deliver it separately, migrate the outbox and set delivery.mode to outbox, then schedule the drain, which the package does not schedule:

Schedule::command('audit-log:drain --until-empty')->everyMinute();

A row on the connection the application's transactions run on commits exactly when they do. Delivery is at least once, in no guaranteed order, and a row that keeps failing is kept rather than deleted, for audit-log:replay --outbox to requeue. See delivery for what each mode guarantees and how to configure a spill channel a replay can read.

Register event definitions and your own context contributors from a service provider's boot(); registration is refused once the application has booted:

AuditLog::define(InvoiceActivity::class);
AuditLog::contribute(OrganisationContributor::class);

A contributor implements ContextContributor and fills only what is still a gap.

In a test, swap the store for a fake that holds what would have been stored:

$fake = AuditLog::fake();

$this->post('/invoices/42/approve');

self::assertTrue($fake->hasRecorded('invoice.approved'));

Secret-shaped keys are redacted everywhere, at capture. This is a heuristic: it cannot find a secret in free text or under an innocuous key, and an event definition, which allowlists a code's fields, is the remedy. See redaction and the threat model. A sign-in identifier is never a property: it is stored as a keyed hash, so failed attempts correlate without keeping the address:

AuditLog::event('app.sign_in_failed')->withIdentifier($email)->failed('invalid_credentials')->record();

Automatic capture

Laravel's authentication events are recorded with no code at all, and Gate denials once capture.gate.enabled is on. Map an event of your own, or an interface its events share, from a service provider's boot(), and it is recorded whenever it is dispatched:

AuditLog::map(OrderShipped::class, OrderShippedMapper::class);

A mapper implements EventMapper: it sets the code and the fields on the builder it is given and returns it, or returns null to skip the event. An event that is never dispatched is captured through its mapper directly. A captured record is written at once, and a failure is reported rather than thrown, unless it ended a transaction the application had open:

AuditLog::capture($event);

Watch a model's changes from boot() too, keeping only the fields named:

AuditLog::watch(Invoice::class, as: 'invoice', fields: ['status', 'amount']);

Record one bulk operation with the manifest of every subject it affected, sealed beside its entry and written after commit like any record. The bound store must keep attachments, as the database store does:

AuditLog::bulk('invoice.voided', $invoices)->record();

What is captured, and the gaps where nothing can be, is in the automatic-capture guide; mapping another package's events, with one row per sign-in, is in the extending guide.

Guides

The contracts behind them, for maintainers and reviewers, are in docs/design.

Requirements

• PHP ^8.3
• Laravel ^12.40 || ^13.3

Testing

composer test               # all suites in parallel (Paratest)
composer test:coverage      # all suites with clover coverage
composer test:unit          # unit suite only
composer test:feature       # feature suite only
composer test:integration   # integration suite only
composer test:performance   # performance budget suite (serial)
composer test:mutation      # scoped mutation gate
composer test:mutation:full # full mutation suite (no thresholds)
composer check              # static analysis + style
composer format             # format the codebase
composer smells             # advisory code smells (duplication, complexity)

Changelog

See CHANGELOG.md for a list of notable changes.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for guidelines on branching, commits, code quality, and pull requests.

Security

If you discover a security vulnerability, please report it responsibly. See SECURITY.md for the disclosure policy and contact details.

License

Licensed under the Apache License, Version 2.0.