Download the PHP package ss-ipg/laravel-auditable without Composer

Laravel Auditable

Declarative model audit logging for Laravel using PHP attributes.

Overview

Laravel Auditable provides a simple, attribute-based approach to audit logging for Eloquent models. Mark any model with the #[Auditable] attribute and all create, update, and delete events are automatically logged with detailed change tracking.

Features

• Declarative #[Auditable] attribute on models
• Tracks created, updated, deleted, soft_deleted, and restored events
• Old/new value tracking for updates
• Column filtering (include, exclude, redact)
• Per-model event filtering
• Soft delete detection
• Boolean cast normalization
• JSON output for log aggregation (Datadog, Splunk, etc.)
• Extensible context providers for custom metadata
• Configurable formatters

Requirements

• PHP 8.3+
• Laravel 11+

Installation

Publish the configuration file:

Quick Start

1. Configure a log channel

Add an audit channel to config/logging.php:

2. Add the attribute to a model

3. Enable audit logging

In your .env file:

That's it! All changes to the model will now be logged.

Configuration

Note: Set environments to ['*'] to enable audit logging in all environments regardless of APP_ENV.

Attribute Options

The #[Auditable] attribute accepts several options:

Examples

Log Output

Each audit entry is a JSON object with the following structure:

Default Fields

These fields are automatically included in every audit entry:

Changes Structure

The changes field varies by event type:

• created: All tracked attribute values
• updated: Only changed attributes with old and new values (or just new values if withOriginal: false)
• deleted, soft_deleted, restored: Only the model ID ({"id": 123})

Soft Delete Detection

When a model uses Laravel's SoftDeletes trait, the package automatically distinguishes between soft deletes and hard deletes:

• soft_deleted: Logged when delete() is called on a soft-deletable model
• deleted: Logged when forceDelete() is called, or when deleting a model without SoftDeletes
• restored: Logged when restore() is called on a soft-deleted model

No configuration is needed—the package detects the SoftDeletes trait automatically.

Cast Normalization

The package respects your model's $casts to prevent false-positive change detection. For example:

This applies to boolean, integer, float, string, array, and json casts.

Context Providers

Context providers allow you to add custom metadata to every audit log entry. Create a class that implements AuditContextProvider:

Register the provider in config/auditable.php:

Custom Formatters

To customize the log output format, create a class that implements AuditFormatter:

Register it in config/auditable.php:

Auditing Pivot Tables

Standard attach(), detach(), and sync() operations bypass Eloquent model events. To audit pivot table changes, use a custom Pivot model:

Then reference it in your relationships:

Testing

The package provides Audit::fake() for testing auditable models without writing to actual log files.

Basic Usage

Available Assertions

Entry Structure

Each captured entry contains:

Known Limitations

• Mass operations bypass events: Model::insert(), Model::update() (query builder), and similar mass operations do not fire Eloquent events and will not be audited. Use model instances for auditable operations.
• Timestamp columns excluded: created_at, updated_at, and deleted_at are always excluded from change tracking (the audit log has its own timestamp).

License

MIT License. See LICENSE for details.