{"id":310,"date":"2025-08-27T19:36:31","date_gmt":"2025-08-27T19:36:31","guid":{"rendered":"https:\/\/1v0.net\/blog\/?p=310"},"modified":"2025-08-27T19:36:33","modified_gmt":"2025-08-27T19:36:33","slug":"how-to-use-eloquent-events-for-auditing-user-actions","status":"publish","type":"post","link":"https:\/\/1v0.net\/blog\/how-to-use-eloquent-events-for-auditing-user-actions\/","title":{"rendered":"How to Use Eloquent Events for Auditing User Actions"},"content":{"rendered":"\n

How to Use Eloquent Events for Auditing User Actions<\/strong><\/h2>\n\n\n\n

Auditing records who did what and when\u2014essential for debugging, compliance, and customer support. With Eloquent events (creating, created, updating, updated, deleting, deleted, restored, forceDeleted), we can capture old\/new values, the actor, and request metadata into an audits<\/em> table. In this guide you\u2019ll build a reusable observer, register it, and ship a simple UI to inspect audit trails.<\/p>\n\n\n\n

<\/div>\n\n\n\n\n

1 – Migration: Audits Table<\/strong><\/h2>\n\n\n\n

Create a generic table to store audit entries for any model using a polymorphic relation. We\u2019ll store the event name, old\/new values, and request context.<\/p>\n\n\n

\/\/ database\/migrations\/2025_08_27_000000_create_audits_table.php<\/span>\nuse<\/span> Illuminate<\/span>\\Database<\/span>\\Migrations<\/span>\\Migration<\/span>;\nuse<\/span> Illuminate<\/span>\\Database<\/span>\\Schema<\/span>\\Blueprint<\/span>;\nuse<\/span> Illuminate<\/span>\\Support<\/span>\\Facades<\/span>\\Schema<\/span>;\n\nreturn<\/span> new<\/span> class<\/span> extends<\/span> Migration<\/span> <\/span>{\n    public<\/span> function<\/span> up<\/span>()<\/span>: void<\/span> <\/span>{\n        Schema::create('audits'<\/span>, function<\/span> (Blueprint $table)<\/span> <\/span>{\n            $table->id();\n            \/\/ polymorphic: auditable_type + auditable_id<\/span>\n            $table->morphs('auditable'<\/span>);\n            \/\/ actor (nullable for system jobs)<\/span>\n            $table->foreignId('user_id'<\/span>)->nullable()->constrained()->nullOnDelete();\n            \/\/ event: created, updated, deleted, restored, force_deleted<\/span>\n            $table->string('event'<\/span>, 32<\/span>);\n            \/\/ JSON diffs<\/span>\n            $table->json('old_values'<\/span>)->nullable();\n            $table->json('new_values'<\/span>)->nullable();\n            \/\/ request context<\/span>\n            $table->string('ip_address'<\/span>, 45<\/span>)->nullable();\n            $table->text('user_agent'<\/span>)->nullable();\n            $table->timestamps();\n            $table->index(['event'<\/span>, 'created_at'<\/span>]);\n        });\n    }\n\n    public<\/span> function<\/span> down<\/span>()<\/span>: void<\/span> <\/span>{\n        Schema::dropIfExists('audits'<\/span>);\n    }\n};<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
This table can attach audits to any model via morphs('auditable')<\/code>. We keep old_values<\/code>\/new_values<\/code> as JSON to store only changed keys for updates and full snapshots for create\/delete if you prefer.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
2 – Audit Model<\/strong><\/h2>\n\n\n\n
Define the Audit<\/code> model with casts and the polymorphic relation back to the auditable model.<\/p>\n\n\n
\/\/ app\/Models\/Audit.php<\/span>\nnamespace<\/span> App<\/span>\\Models<\/span>;\n\nuse<\/span> Illuminate<\/span>\\Database<\/span>\\Eloquent<\/span>\\Model<\/span>;\n\nclass<\/span> Audit<\/span> extends<\/span> Model<\/span>\n<\/span>{\n    protected<\/span> $fillable = [\n        'auditable_type'<\/span>,'auditable_id'<\/span>,'user_id'<\/span>,'event'<\/span>,\n        'old_values'<\/span>,'new_values'<\/span>,'ip_address'<\/span>,'user_agent'<\/span>\n    ];\n\n    protected<\/span> $casts = [\n        'old_values'<\/span> => 'array'<\/span>,\n        'new_values'<\/span> => 'array'<\/span>,\n    ];\n\n    public<\/span> function<\/span> auditable<\/span>()<\/span>\n    <\/span>{\n        return<\/span> $this<\/span>->morphTo();\n    }\n\n    public<\/span> function<\/span> user<\/span>()<\/span>\n    <\/span>{\n        return<\/span> $this<\/span>->belongsTo(User::class);\n    }\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Casting JSON arrays makes reading diffs straightforward in controllers and Blade. The auditable()<\/code> morph lets you navigate back to the source record.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
3 – Reusable Observer to Capture Events<\/strong><\/h2>\n\n\n\n
The observer listens to Eloquent lifecycle events, computes diffs, redacts sensitive fields, and writes an Audit<\/code> entry. Attach the same observer to any model you want to audit.<\/p>\n\n\n
\/\/ app\/Observers\/GenericAuditObserver.php<\/span>\nnamespace<\/span> App<\/span>\\Observers<\/span>;\n\nuse<\/span> App<\/span>\\Models<\/span>\\Audit<\/span>;\nuse<\/span> Illuminate<\/span>\\Database<\/span>\\Eloquent<\/span>\\Model<\/span>;\nuse<\/span> Illuminate<\/span>\\Support<\/span>\\Arr<\/span>;\nuse<\/span> Illuminate<\/span>\\Support<\/span>\\Facades<\/span>\\Auth<\/span>;\nuse<\/span> Illuminate<\/span>\\Support<\/span>\\Facades<\/span>\\Request<\/span>;\n\nclass<\/span> GenericAuditObserver<\/span>\n<\/span>{\n    \/**\n     * Keys to hide in audits (passwords, tokens, secrets).\n     *\/<\/span>\n    protected<\/span> array<\/span> $redacted = ['password'<\/span>,'remember_token'<\/span>,'api_key'<\/span>,'secret'<\/span>,'token'<\/span>];\n\n    protected<\/span> function<\/span> redact<\/span>(array $data)<\/span>: array<\/span>\n    <\/span>{\n        foreach<\/span> ($this<\/span>->redacted as<\/span> $key) {\n            if<\/span> (Arr::has($data, $key)) {\n                Arr::set($data, $key, '***redacted***'<\/span>);\n            }\n        }\n        return<\/span> $data;\n    }\n\n    protected<\/span> function<\/span> context<\/span>()<\/span>: array<\/span>\n    <\/span>{\n        return<\/span> [\n            'user_id'<\/span>    => Auth::id(),\n            'ip_address'<\/span> => Request::ip(),\n            'user_agent'<\/span> => Request::header('User-Agent'<\/span>),\n        ];\n    }\n\n    public<\/span> function<\/span> created<\/span>(Model $model)<\/span>: void<\/span>\n    <\/span>{\n        Audit::create([\n            'auditable_type'<\/span> => get_class($model),\n            'auditable_id'<\/span>   => $model->getKey(),\n            'event'<\/span>          => 'created'<\/span>,\n            'old_values'<\/span>     => null<\/span>,\n            'new_values'<\/span>     => $this<\/span>->redact($model->getAttributes()),\n        ] + $this<\/span>->context());\n    }\n\n    public<\/span> function<\/span> updated<\/span>(Model $model)<\/span>: void<\/span>\n    <\/span>{\n        \/\/ changed attributes only<\/span>\n        $changes = $model->getChanges();             \/\/ new values for dirty fields<\/span>\n        $original = Arr::only($model->getOriginal(), array_keys($changes));\n\n        Audit::create([\n            'auditable_type'<\/span> => get_class($model),\n            'auditable_id'<\/span>   => $model->getKey(),\n            'event'<\/span>          => 'updated'<\/span>,\n            'old_values'<\/span>     => $this<\/span>->redact($original),\n            'new_values'<\/span>     => $this<\/span>->redact($changes),\n        ] + $this<\/span>->context());\n    }\n\n    public<\/span> function<\/span> deleted<\/span>(Model $model)<\/span>: void<\/span>\n    <\/span>{\n        Audit::create([\n            'auditable_type'<\/span> => get_class($model),\n            'auditable_id'<\/span>   => $model->getKey(),\n            'event'<\/span>          => 'deleted'<\/span>,\n            'old_values'<\/span>     => $this<\/span>->redact($model->getAttributes()),\n            'new_values'<\/span>     => null<\/span>,\n        ] + $this<\/span>->context());\n    }\n\n    public<\/span> function<\/span> restored<\/span>(Model $model)<\/span>: void<\/span>\n    <\/span>{\n        Audit::create([\n            'auditable_type'<\/span> => get_class($model),\n            'auditable_id'<\/span>   => $model->getKey(),\n            'event'<\/span>          => 'restored'<\/span>,\n            'old_values'<\/span>     => null<\/span>,\n            'new_values'<\/span>     => null<\/span>,\n        ] + $this<\/span>->context());\n    }\n\n    public<\/span> function<\/span> forceDeleted<\/span>(Model $model)<\/span>: void<\/span>\n    <\/span>{\n        Audit::create([\n            'auditable_type'<\/span> => get_class($model),\n            'auditable_id'<\/span>   => $model->getKey(),\n            'event'<\/span>          => 'force_deleted'<\/span>,\n            'old_values'<\/span>     => null<\/span>,\n            'new_values'<\/span>     => null<\/span>,\n        ] + $this<\/span>->context());\n    }\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
The observer captures five major events. For updates, it stores only changed keys by diffing getOriginal()<\/code> vs getChanges()<\/code>. The $redacted<\/code> list ensures secrets never leak into the audit log.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
4 – Register the Observer<\/strong><\/h2>\n\n\n\n
You can observe multiple models. Here we audit User<\/code> and Post<\/code>. Add more as needed.<\/p>\n\n\n
\/\/ app\/Providers\/AppServiceProvider.php (boot)<\/span>\nuse<\/span> App<\/span>\\Models<\/span>\\Post<\/span>;\nuse<\/span> App<\/span>\\Models<\/span>\\User<\/span>;\nuse<\/span> App<\/span>\\Observers<\/span>\\GenericAuditObserver<\/span>;\n\npublic<\/span> function<\/span> boot<\/span>()<\/span>: void<\/span>\n<\/span>{\n    User::observe(GenericAuditObserver::class);\n    Post::observe(GenericAuditObserver::class);\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Placing this in AppServiceProvider::boot()<\/code> wires the observer globally. From now on, creates\/updates\/deletes on these models produce audit rows automatically.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
5 – (Optional) Auditable Trait for Model-Side Opt-In<\/strong><\/h2>\n\n\n\n
If you prefer models to opt-in explicitly, use a trait that registers the observer on boot. This avoids listing models in the provider.<\/p>\n\n\n
\/\/ app\/Models\/Concerns\/Auditable.php<\/span>\nnamespace<\/span> App<\/span>\\Models<\/span>\\Concerns<\/span>;\n\nuse<\/span> App<\/span>\\Observers<\/span>\\GenericAuditObserver<\/span>;\n\ntrait<\/span> Auditable\n{\n    public<\/span> static<\/span> function<\/span> bootAuditable<\/span>()<\/span>: void<\/span>\n    <\/span>{\n        static<\/span>::observe(GenericAuditObserver::class);\n    }\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Attach the trait to any model you want audited: use Auditable;<\/code>. When the model boots, it registers the observer automatically.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
6 – Querying the Audit Log<\/strong><\/h2>\n\n\n\n
A controller to filter audits by model, event, date range, or user. We\u2019ll display results in a simple Blade table.<\/p>\n\n\n
\/\/ app\/Http\/Controllers\/AuditController.php<\/span>\nnamespace<\/span> App<\/span>\\Http<\/span>\\Controllers<\/span>;\n\nuse<\/span> App<\/span>\\Models<\/span>\\Audit<\/span>;\nuse<\/span> Illuminate<\/span>\\Http<\/span>\\Request<\/span>;\n\nclass<\/span> AuditController<\/span> extends<\/span> Controller<\/span>\n<\/span>{\n    public<\/span> function<\/span> index<\/span>(Request $request)<\/span>\n    <\/span>{\n        $q = Audit::query()\n            ->with(['user'<\/span>])\n            ->latest();\n\n        if<\/span> ($m = $request->input('model'<\/span>)) {\n            \/\/ expects fully-qualified class or short name<\/span>\n            $q->where('auditable_type'<\/span>, $m);\n        }\n\n        if<\/span> ($e = $request->input('event'<\/span>)) {\n            $q->where('event'<\/span>, $e);\n        }\n\n        if<\/span> ($u = $request->input('user_id'<\/span>)) {\n            $q->where('user_id'<\/span>, $u);\n        }\n\n        if<\/span> ($from = $request->date('from'<\/span>)) {\n            $q->whereDate('created_at'<\/span>, '>='<\/span>, $from);\n        }\n        if<\/span> ($to = $request->date('to'<\/span>)) {\n            $q->whereDate('created_at'<\/span>, '<='<\/span>, $to);\n        }\n\n        $audits = $q->paginate(15<\/span>)->withQueryString();\n        return<\/span> view('audits.index'<\/span>, compact('audits'<\/span>));\n    }\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
The controller builds a flexible query over the audits<\/code> table. We eager-load the actor (user<\/code>) and support common filters to narrow results.<\/p>\n\n\n\n
\/\/ routes\/web.php (snippet)<\/span>\nuse<\/span> App<\/span>\\Http<\/span>\\Controllers<\/span>\\AuditController<\/span>;\n\nRoute::middleware(['auth'<\/span>])->group(function<\/span> ()<\/span> <\/span>{\n    Route::get('\/audits'<\/span>, [AuditController::class, 'index'<\/span>])->name('audits.index'<\/span>);\n});<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Audit visibility should be restricted\u2014only admins or support roles should access this page. Protect the route with auth<\/code> and authorization policies as needed.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
7 – UI: Audit Log Blade with Filters<\/strong><\/h2>\n\n\n\n
A minimal interface to explore audit entries, see who changed what, and inspect JSON diffs quickly.<\/p>\n\n\n
<!-- resources\/views\/audits\/index.blade.php -->\n@extends('layouts.app'<\/span>)\n\n@section('content'<\/span>)\n<div class<\/span>=\"container<\/span>\">\n  <h1<\/span> class<\/span>=\"mb<\/span>-4\">Audit<\/span> Log<\/span><\/h1<\/span>>\n\n  <form<\/span> method<\/span>=\"GET<\/span>\" class<\/span>=\"row<\/span> g<\/span>-2 mb<\/span>-4\">\n    <div<\/span> class<\/span>=\"col<\/span>-md<\/span>-3\">\n      <input<\/span> name<\/span>=\"model<\/span>\" class<\/span>=\"form<\/span>-control<\/span>\" placeholder<\/span>=\"Model<\/span> (FQCN<\/span>)\" value<\/span>=\"<\/span>{{ request('model'<\/span>) }}\" \/>\n    <\/div>\n    <div class=\"<\/span>col-md-2<\/span>\">\n      <select name=\"<\/span>event\" class=\"<\/span>form-select\">\n        @php $events = ['created','updated','deleted','restored','force_deleted']; @endphp\n        <option value=\"<\/span>\">Any event<\/option>\n        @foreach($events as $e)\n          <option value=\"<\/span>{{ $e }}\" {{ request('event')===$e ? 'selected' : '' }}>{{ ucfirst(str_replace('_',' ',$e)) }}<\/option>\n        @endforeach\n      <\/select>\n    <\/div>\n    <div class=\"<\/span>col-md-2<\/span>\">\n      <input type=\"<\/span>number\" name=\"<\/span>user_id\" class=\"<\/span>form-control\" placeholder=\"<\/span>User ID\" value=\"<\/span>{{ request('user_id'<\/span>) }}\" \/>\n    <\/div>\n    <div class=\"<\/span>col-md-2<\/span>\">\n      <input type=\"<\/span>date\" name=\"<\/span>from\" class=\"<\/span>form-control\" value=\"<\/span>{{ request('from'<\/span>) }}\" \/>\n    <\/div>\n    <div class=\"<\/span>col-md-2<\/span>\">\n      <input type=\"<\/span>date\" name=\"<\/span>to\" class=\"<\/span>form-control\" value=\"<\/span>{{ request('to'<\/span>) }}\" \/>\n    <\/div>\n    <div class=\"<\/span>col-md-1<\/span> d-grid\">\n      <button class=\"<\/span>btn btn-theme\">Filter<\/button>\n    <\/div>\n  <\/form>\n\n  @forelse($audits as $audit)\n    <div class=\"<\/span>card mb-3<\/span>\">\n      <div class=\"<\/span>card-body\">\n        <div class=\"<\/span>d-flex justify-content-between align-items-center\">\n          <div>\n            <strong>{{ class_basename($audit->auditable_type) }}#{{ $audit->auditable_id }}<\/strong>\n            <span class=\"<\/span>badge bg-secondary\">{{ $audit->event }}<\/span>\n          <\/div>\n          <small class=\"<\/span>text-muted\">{{ $audit->created_at }} by {{ optional($audit->user)->name ?? 'system' }}<\/small>\n        <\/div>\n\n        <div class=\"<\/span>mt-3<\/span>\">\n          <details>\n            <summary>Old Values<\/summary>\n            <pre class=\"<\/span>mb-0<\/span>\">{{ json_encode($audit->old_values, JSON_PRETTY_PRINT|JSON_UNESCAPED_SLASHES) }}<\/pre>\n          <\/details>\n          <details class=\"<\/span>mt-2<\/span>\">\n            <summary>New Values<\/summary>\n            <pre class=\"<\/span>mb-0<\/span>\">{{ json_encode($audit->new_values, JSON_PRETTY_PRINT|JSON_UNESCAPED_SLASHES) }}<\/pre>\n          <\/details>\n        <\/div>\n\n        <small class=\"<\/span>text-muted\">IP: {{ $audit->ip_address }} | Agent: {{ Str::limit($audit->user_agent, 80) }}<\/small>\n      <\/div>\n    <\/div>\n  @empty\n    <p class=\"<\/span>text-muted\">No audit entries found.<\/p>\n  @endforelse\n\n  {{ $audits->links() }}\n<\/div>\n@endsection<\/span><\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
The page shows each event with who did it and when. Expandable <details><\/code> blocks display JSON diffs without overwhelming the layout. Filters make it easy to narrow down incidents.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
8 – Applying Auditing to a Model<\/strong><\/h2>\n\n\n\n
Here\u2019s how you would opt-in a typical model (e.g., Post<\/code>). We\u2019ll also show a quick controller action to trigger events.<\/p>\n\n\n
\/\/ app\/Models\/Post.php (snippet)<\/span>\nnamespace<\/span> App<\/span>\\Models<\/span>;\n\nuse<\/span> Illuminate<\/span>\\Database<\/span>\\Eloquent<\/span>\\Model<\/span>;\nuse<\/span> Illuminate<\/span>\\Database<\/span>\\Eloquent<\/span>\\SoftDeletes<\/span>;\nuse<\/span> App<\/span>\\Models<\/span>\\Concerns<\/span>\\Auditable<\/span>;\n\nclass<\/span> Post<\/span> extends<\/span> Model<\/span>\n<\/span>{\n    use<\/span> SoftDeletes<\/span>, Auditable<\/span>;\n\n    protected<\/span> $fillable = ['user_id'<\/span>,'title'<\/span>,'body'<\/span>,'status'<\/span>];\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Including Auditable<\/code> ensures the observer is registered for Post<\/code>. Combining with SoftDeletes<\/code> records deleted<\/em>, restored<\/em>, and force_deleted<\/em> events as well.<\/p>\n\n\n\n
\/\/ app\/Http\/Controllers\/PostController.php (snippet)<\/span>\npublic<\/span> function<\/span> update<\/span>(Request $request, Post $post)<\/span>\n<\/span>{\n    $data = $request->validate([\n        'title'<\/span> => ['required'<\/span>,'string'<\/span>,'max:150'<\/span>],\n        'body'<\/span>  => ['required'<\/span>,'string'<\/span>],\n        'status'<\/span>=> ['required'<\/span>,'in:draft,published'<\/span>],\n    ]);\n\n    $post->update($data); \/\/ triggers \"updated\" audit<\/span>\n    return<\/span> back()->with('status'<\/span>,'Post updated.'<\/span>);\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Saving the model is all that\u2019s needed\u2014events fire automatically, the observer writes the audit, and you can view it in the Audit Log UI.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
Wrapping Up<\/h2>\n\n\n\n
You built a robust audit trail with Eloquent events: a polymorphic audits table, a reusable observer that records diffs and request context, registration via provider or trait, and a filterable UI. This approach is lightweight, framework-native, and easy to extend with policies, retention rules, or offloading to a log index if volumes grow.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
What\u2019s Next<\/h2>\n\n\n\n