Download the PHP package aw3r1se/laravel-audit-core without Composer

laravel-audit-core

Eloquent model and relation change auditing for Laravel, with a pluggable delivery transport. Records create/update/delete state plus relation mutations (attach/detach/sync/toggle/associate/pivot updates) into a request-scoped buffer, then dispatches a single event per request.

It is Octane/RoadRunner safe: the buffer is a scoped singleton and is always resolved inside the recording closures, never captured at model boot.

What this package does not do

It does not talk to any storage or message broker, and it has no read API. The buffer is handed to a transport you provide. The read side (querying past audit logs, presentation, localization) stays in your application — this package is purely the recording engine.

Install

The service provider is auto-discovered.

Usage

1. Make a model auditable

$auditIgnoredFields is merged with the global config('audit.ignored_fields'), so you only list the extras. For computed values, override getAuditIgnoredFields() / getAuditIgnoredRelations() instead.

The trait overrides the Eloquent relation factory methods, so relation changes on belongsTo, hasOne/Many, morphOne/Many, belongsToMany and morphToMany are audited automatically. No changes to your relation definitions are needed.

Weak entities (no primary key)

Some child records have no key of their own ($incrementing = false, no surrogate id). For those, getKey() is null, so a recorded id would be meaningless. The engine detects this and falls back to a filtered attribute snapshot of the row (honouring getHidden() and the ignored fields), both in the relation payload (attached/detached) and in a model's own model_id. You get the actual state of the change instead of null.

Recording strategy: diff vs snapshot

By default each model event is recorded as a diff — new attributes on create, changed attributes on update, the original row on delete. You can instead record a snapshot: the model's full filtered attributes plus a recursive snapshot of selected relations.

Pick the default for every model in config, and override it per model:

A snapshot entry's state looks like:

Relations are queried fresh at capture time (honouring getHidden() and the ignored fields, same as attributes), so the snapshot reflects current persisted state. Deletions are captured on deleting, while relations are still attached.

This only shapes a model's own create/update/delete entry; relation-mutation recording (attach/detach/sync) is independent and runs under either strategy. To add your own strategy, implement Aw3r1se\Audit\Contracts\AuditStrategy and register it under config('audit.strategies') (or reference it by class-string).

2. Attach the middleware

Add Aw3r1se\Audit\Http\Middleware\AuditActions to the route group you want audited (typically your API). It records every POST/PUT/PATCH/DELETE and dispatches Aw3r1se\Audit\Events\UserActionEvent carrying an immutable AuditEvent. Pass route arguments to exclude request keys from the captured body, e.g. ->middleware(AuditActions::class.':password').

3. Provide a transport

Implement Aw3r1se\Audit\Contracts\AuditTransport and point config at it:

The package ships NullTransport (default, no-op) and LogTransport (PSR-3). Delivery runs through the queued ForwardAuditToTransport listener, so it never blocks the request — configure your queue accordingly.

Configuration

Testing