Why audit?

Good question... until one day you suddenly discover that you really needed that paper trail. Where did that file go, who deleted it? Who logged in, when and why? Audit trails are essential for keeping track of activity on your installations, and satisfying the requirements of your customers and security compliance.

For those that have been on the receiving end of challenges like this, it can be a pretty sticky situation, and audit logs will help you get out of that mess!

So that's the why out the way, and now lets get on to the how...

Installation

I've written this package to be as quick and easy as it can possibly be to get installed and working. You'll literally have auditing in your application within minutes and with minimum hassle!

Install the package

Just use composer to install the latest version.

composer require motomedialab/simple-laravel-audit

Run your migrations

As part of the package, we've configured a migration. You just need to run it, and this will make a table called audit_logs

php artisan migrate

And that's it, as far as basic package setup is concerned, that's all you need to do! You can now call on the audit package whenever, and wherever you need.

Recording logins, login failures, and lockouts...

Lets give an example of how we can achieve this... Probably the most fundamental things you'd want to audit in an application is authentication events.

Fortunately, Laravel already emits a number of events when it comes to authentication that we can tap into. We'll write some code to listen out for those so that we can write them out to our audit log table.

Create a listener

Laravel emits countless events after certain actions are taken. Some are listened to by default, but most just emit so that we can tap into them at a later date, and that's exactly what we'll do now. We'll create our listener in the App\Listeners namespace.

This listener is a simple class with a handle method that accepts the event given to it, and writes out an audit log using the global audit helper. The audit helper will automatically record the user (where applicable) and IP address the action was initiated from.

app/Listeners/AuthEventListener.php

<?php

namespace App\Listeners;

class AuthEventListener
{
    public function handle($event): void
    {
        audit(class_basename($event));
    }
}

However, despite our listener being in place, we need to let Laravel know what events we want our listener to actually listen for. Lets do that by registering a service provider.

Create a Service Provider

We'll create a new service provider to define what events should be listened for, we'll call it AuditServiceProvider. All we need to do is create the boot method (which is called by Laravel by default) and listen to certain Auth events being called.

Those events will then get passed on to the listener that we've just created.

app/Providers/AuditServiceProvider.php

<?php

namespace App\Providers;

use Illuminate\Auth\Events;
use App\Listeners\AuthEventListener;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\ServiceProvider;

class AuditServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Event::listen([
            Events\Login::class,
            Events\Logout::class,
            Events\Lockout::class,
            Events\Failed::class
        ], AuthEventListener::class);
    }
}

Register your Service Provider

So Laravel knows what we've just created, you'll need to register your Service Provider. If you're in Laravel 11, we just need to stick it into our boostrap/providers.php array, like below:

<?php

return [
    App\Providers\AppServiceProvider::class,
    App\Providers\AuditServiceProvider::class,
];

And we're done! Now, whenever a login, logout, lockout or login failure event gets emitted by Laravel, our listener will pick it up and it'll get logged straight to our audit_logs table, ready for review.

It really couldn't be much simpler. This is just one use of the audit package, but you can use it wherever you need to in your application.

The package offers more configuration and slightly more complex use cases, so check it out on GitHub - https://github.com/motomedialab/simple-laravel-audit

If you liked this article, please consider subscribing for more updates like this!