Skip to content

Audit Trail

View raw .md
On this page

Introduction#

The audit trail answers who changed what, when, and from where. With the feature on, every Eloquent create, update and delete in the application is written to magic_starter_audits, together with the acting user and the request it came from. Writes made through the admin panel are recorded as one admin.* row each.


Enabling#

Audit is opt-in:

php
// config/magic-starter.php
'features' => [
    Features::audit(),
],

Run php artisan magic-starter:install --features=audit to publish the migration, then php artisan migrate. While the feature is off, no listener is registered and model events cost nothing extra.


What Is Recorded#

Column Content
event created, updated, deleted, or an explicit name such as admin.user.updated
auditable_type, auditable_id The record the event is about
actor_type, actor_id The authenticated user, when there is one
related_user_id The user the row concerns: the subject itself for a user, otherwise its user_id
old_values, new_values For an update, only the changed keys, with the raw values they held before
context ip, user_agent, url (without its query string) and route

Key columns are strings, so one column holds integer and UUID keys alike. A row is inserted after the surrounding transaction commits; a change that rolls back leaves no row.


Excluding Models#

php
'audit' => [
    'exclude' => [
        \Laravel\Sanctum\PersonalAccessToken::class,
        \App\Models\PageView::class,
    ],
],

exclude lists model classes, subclasses included. The default holds Sanctum's PersonalAccessToken, which stamps last_used_at on every authenticated request and would otherwise write a row per API call; keep it when you add your own. The package always skips its own Audit model, every pivot and the team membership model.


Ignoring Attributes#

A column that moves on every tick, such as last_checked_at, would write a row per tick. Name it as ignored and an update that changes nothing else is not recorded:

php
// config/magic-starter.php
'audit' => [
    'ignore' => [
        \App\Models\Monitor::class => ['last_checked_at', 'last_status'],
    ],
],
php
class Monitor extends Model
{
    protected array $auditIgnore = ['last_checked_at', 'last_status'];
}

ignore maps a model class (subclasses included) to its attributes, and the model's own $auditIgnore adds to that list. An update whose changes are all ignored, apart from updated_at, writes no row. A mixed update is recorded without the ignored keys. A model with no ignore list is audited in full, so even a bare touch() on it writes a row; on a model with one, a touch() that moved no ignored attribute is recorded too. Credential columns (password, remember_token, two_factor_secret, two_factor_recovery_codes, token, device_id) cannot be ignored: a change to one is always recorded, redacted.


Redaction#

A sensitive value is stored as [redacted]; the key stays, so a reader can see that the field changed. A value is redacted when:

  • the model lists it in $hidden;
  • it is cast encrypted, encrypted:array (and the other encrypted casts) or hashed;
  • the model names it in its own $auditExclude property;
  • it is password, remember_token, two_factor_secret, two_factor_recovery_codes, token or device_id (a guest's device_id signs that guest in through POST auth/guest, so it is a credential);
  • it is listed in audit.redact.
php
// config/magic-starter.php
'audit' => [
    'redact' => ['api_key'],
],
php
class Invoice extends Model
{
    protected array $auditExclude = ['internal_note'];
}

audit.redact extends the built-in list and can never shorten it, so a published config cannot start storing a password. Old values are stored raw, as the database held them, so an encrypted column appears as ciphertext, never as plaintext.


Recording an Event#

For something that is not a model change, such as an impersonation or an export:

php
use FlutterSdk\MagicStarter\Audit\Auditor;

Auditor::record('admin.user_impersonated', $user, [
    'reason' => 'support ticket 4411',
]);

The signature is record(string $event, ?Model $subject, array $context = [], ?Authenticatable $actor = null). The actor defaults to the authenticated user, and $context is merged over the request context. It writes nothing while the feature is off.

Newsletter events#

With newsletter-subscription on, consent changes are recorded under explicit event names on the subscriber row:

Event When Context
newsletter.subscribed A user consents, from the profile toggle or at registration consent_version, source
newsletter.unsubscribed A subscription is withdrawn; nothing is written when it already was via: profile, one_click (the public link) or staff
admin.newsletter.subscriber_deactivated Staff run "Deactivate" in the admin panel the admin action row, beside the newsletter.unsubscribed row

The one-click POST carries the token in its URL, so that row's url is stored as null: no audit row ever holds an unsubscribe token. The token is also in the model's $hidden, so a row that records the subscriber stores it as [redacted].


Silencing the Listener#

php
Auditor::withoutAuditing(function () use ($team): void {
    $team->update(['name' => 'Renamed by a migration script']);
});

Only the model listener is silenced, and nested calls are safe. An explicit Auditor::record() inside the callback is still written: suppress the noise, then record the one event that matters.


Reading the Trail#

Add the HasAudits trait to a model to get an audits() relation:

php
use FlutterSdk\MagicStarter\Audit\HasAudits;

class Team extends Model
{
    use HasAudits;
}

Recording never depends on the trait; it only adds the read side. With the admin panel installed, the Audits resource and a tab on Users and Teams show the same rows.


Pruning#

bash
php artisan magic-starter:audit:prune

Deletes rows older than magic-starter.audit.retention_days (365 by default, and never less than one day), in chunks of 1000. While the feature is on, the package schedules it daily with withoutOverlapping(); your application's scheduler has to be running.


Deleting a User#

A deleted account's trail is personal data and goes with it. Deleting the user model records no row of its own. Once the transaction commits, Auditor::forgetUser() runs:

  • every row whose subject is that user is deleted;
  • every row whose related_user_id is that user (their teams, linked accounts) is deleted;
  • every row where they were the actor stays, with actor_id set to null, actor_type kept, and ip and user_agent removed from context: what happened to somebody else's record remains, who did it does not.

A deletion that rolls back erases nothing.

The purge finds rows by user key only. A row keyed by an email address elsewhere is not covered: a team invitation (its values hold the invited address and it relates to the team, not to a user) keeps its audit rows. Delete those yourself when your obligations require it.

A newsletter subscription is covered, but not by the purge: DeleteUser deletes the user's subscriber row (found by user_id, or by address for a row nobody has claimed yet) together with that row's audit rows, inside the deletion's transaction.


What Is Not Captured#

  • Query-builder bulk writes (Model::query()->update(), ->delete(), DB::table()), which fire no model events.
  • Pivot and team membership rows.
  • Writes made with model events muted, such as saveQuietly().
  • Models in audit.exclude, and anything inside Auditor::withoutAuditing().

When such a write matters, wrap it in Auditor::record().

esc

Search index did not load.

No match for "".

Try a class like rounded-lg or a widget like WButton.