Download the PHP package jeylabs/laravel-audit-log without Composer

Log audit inside your Laravel app

The jeylabs/laravel-audit-log package provides easy to use functions to log the activities of the users of your app. It can also automatically log model events. All activity will be stored in the audit_logs table.

You can retrieve all activity using the Jeylabs\Auditlog\Models\AuditLog model.

Here's a more advanced example:

Calling $auditLog->changes will return this array:

Installation

You can install the package via composer:

The service provider is auto-discovered (Laravel's package auto-discovery), so there's no manual step to register it. If you've disabled auto-discovery for this package, add it to bootstrap/providers.php (Laravel 11+) or config/app.php's providers array (older apps) yourself:

You can publish the migration with:

Note: The default migration assumes you are using integers for your model IDs. If you are using UUIDs, or some other format, adjust the format of the subject_id and causer_id fields in the published migration before continuing.

After the migration has been published you can create the audit-logs table by running the migrations:

You can optionally publish the config file with:

This is the contents of the published config file:

Storing and accessing audit logs in MySQL, PostgreSQL, MongoDB, or DynamoDB

Every write goes through the Jeylabs\AuditLog\Contracts\AuditLogStore contract, and which concrete backend it talks to is picked by laravel-audit-log.driver. auditLog()->log(...), LogsAudit's automatic model-event logging, CausesAudit, the auditlog:clean command, and the visitor-location controller all work the same way regardless of driver — only the driver-specific setup below changes.

MySQL / PostgreSQL (and SQLite, SQL Server)

This is the default eloquent driver and needs nothing beyond the standard installation above — Eloquent is database-agnostic, so pointing your app's default database connection at MySQL or PostgreSQL (any currently supported version) just works. subject()/causer() relations, AuditLog::causedBy()/forSubject()/inLog() scopes, and $user->auditLog/$user->activity (via LogsAudit/CausesAudit) are all fully supported.

The unit tests exercise this same EloquentAuditLogStore code path against sqlite. To also run it against a live MySQL or PostgreSQL server (catches anything sqlite's more lenient typing papers over):

tests/Integration/MySqlLocalIntegrationTest.php and tests/Integration/PostgresLocalIntegrationTest.php skip themselves when their respective env var isn't set, so they're a no-op in normal composer test runs / CI without those servers available.

MongoDB

1. composer require mongodb/laravel-mongodb (and the PHP mongodb extension) — not a dependency of this package, since most apps don't need it.
2. Configure a mongodb connection in config/database.php per that package's docs.
3. Set AUDIT_LOGGER_DRIVER=mongodb (or 'driver' => 'mongodb' in the published config).

Audit logs are then written through Jeylabs\AuditLog\Models\MongoAuditLog, which mirrors the SQL AuditLog model (same relations, scopes, and casts) on top of mongodb/laravel-mongodb's Eloquent-compatible base model, including cross-database (subject/causer) relations to your normal SQL models.

The unit tests run the mongodb driver's code path against sqlite (both go through the same EloquentAuditLogStore), so they need no MongoDB server. To also exercise the real mongodb/laravel-mongodb + ext-mongodb stack against a live MongoDB:

tests/Integration/MongoDbLocalIntegrationTest.php skips itself when MONGODB_LOCAL_URI isn't set (or the mongodb extension isn't loaded), so it's a no-op in normal composer test runs / CI without a Mongo instance available.

DynamoDB

DynamoDB has no joins or secondary query engine, so subject()/causer() relations and the $user->auditLog/$user->activity traits are not available under this driver (resolving them throws InvalidConfiguration) — use AuditLogStore::causedBy()/forSubject() directly instead:

Setup:

1. composer require async-aws/dynamo-db (a lightweight independent client, not the full aws/aws-sdk-php) — or bind your own implementation of Jeylabs\AuditLog\Contracts\DynamoDbClient in a service provider if you'd rather use the full AWS SDK or another client.
2. Provision the table yourself (this package does not create it) with:
   • Partition key: id (String)
   • A Global Secondary Index named causer_index (configurable via stores.dynamodb.causer_index) with partition key causer_key (String)
   • A Global Secondary Index named subject_index (configurable via stores.dynamodb.subject_index) with partition key subject_key (String)
3. Set AUDIT_LOGGER_DRIVER=dynamodb and the AUDIT_LOGGER_DYNAMODB_* environment variables (region, table, endpoint, credentials).

auditlog:clean has no efficient range-delete on DynamoDB, so it falls back to a full table scan for this driver — fine for occasional maintenance, but for production-scale cleanup set stores.dynamodb.delete_records_older_than_days_via_ttl to a day count and enable DynamoDB's native TTL on the ttl attribute in the table settings; expired items are then removed automatically with no scan needed.

The unit tests mock Jeylabs\AuditLog\Contracts\DynamoDbClient, so they need no AWS access. To also exercise the real async-aws wire protocol (marshaling, CreateTable/GSIs, queries) against DynamoDB Local:

tests/Integration/DynamoDbLocalIntegrationTest.php skips itself when DYNAMODB_LOCAL_ENDPOINT isn't set, so it's a no-op in normal composer test runs / CI without a Dynamo endpoint available.

Logging model events

A neat feature of this package is that it can automatically log events such as when a model is created, updated and deleted. To make this work all you need to do is let your model use the Jeylabs\AuditLog\Traits\LogsAudit-trait.

As a bonus the package will also log the changed attributes for all these events when setting $logAttributes property on the model.

Here's an example:

Let's see what gets logged when creating an instance of that model.

Now let's update some that $newsItem.

Calling $auditLog->changes will return this array:

Now, what happens when you call delete?

Customizing the events being logged

By default the package will log the created, updated, deleted events. You can modify this behaviour by setting the $recordEvents property on a model.

Customizing the description

By default the package will log created, updated, deleted in the description of the activity. You can modify this text by overriding the getDescriptionForEvent function.

Let's see what happens now:

Ignoring changes to certain attributes

If your model contains attributes whose change don't need to trigger an activity being logged you can use $ignoreChangedAttributes

Changing text will not trigger an audit being logged.

By default the updated_at attribute is not ignored and will trigger an activity being logged. You can simply add the updated_at attribute to the $ignoreChangedAttributes array to override this behaviour.

Logging only the changed attributes

If you do not want to log every attribute in your $logAttributes variable, but only those that has actually changed after the update, you can use $logOnlyDirty

Changing only name means only the name attribute will be logged in the activity, and text will be left out.

Using the CausesAudit trait

The package ships with a CausesAudit trait which can be added to any model that you use as a causer. It provides an auditLog relationship which returns all activities that are caused by the model.

If you include it in the User model you can simply retrieve all the current users activities like this: