Download the PHP package dineshstack/laravel-audit without Composer

dineshstack/laravel-audit

Activity log & audit trail for Laravel 13. Auto-log every Eloquent model change — with field-level diffs, IP capture, user attribution, batch grouping, data masking, and a full REST API — in one composer require.

Why this package?

Most Laravel audit packages store a flat JSON blob and call it done. laravel-audit goes further:

• Field-level diffs — exactly which columns changed, from what value, to what value
• Sensitive-field masking — password, api_key, card_number, and any custom field are stored as [REDACTED] automatically
• Batch grouping — wrap multiple operations in AuditLog::batch() and every entry shares a batch_id so you can replay a full transaction
• Alert rules — define threshold rules (e.g. "more than 10 deletes per minute") that fire Mailgun emails or Slack webhooks
• Retention pruning — auto-scheduled daily cleanup via audit:prune; configurable retention window
• REST API — nine endpoints covering feed, timeline, stats, export (CSV + PDF), and alert rule management, ready to power any dashboard or SIEM integration

Requirements

Installation

audit:install publishes config/audit.php, publishes and optionally runs the migration, and appends the required environment variable stubs to your .env file.

If you prefer to publish assets manually:

Quick start

1. Auto-log any Eloquent model

Add the LogsActivity trait to the models you want to audit:

That's it. Every create, update, and delete on Invoice is now logged with the changed attributes, old and new values, the authenticated user, their IP address, user agent, and the full request URL.

2. Manual logging

Use the fluent builder for events that aren't model-driven:

All methods except log() and save() are optional:

3. Batch logging

Wrap multiple operations in AuditLog::batch() to link them under a shared batch_id. This lets you query or replay an entire multi-step transaction as a unit:

All entries created inside the closure share the same UUID batch_id.

Field-level diffs

When a model is updated, the package computes a precise diff of only the changed fields:

Unchanged fields are never stored. Added fields report "type": "added" with old: null; removed fields report "type": "removed" with new: null.

Controlling which fields are logged

Override these two methods in your model:

Data masking

Any field whose name contains a masked keyword is stored as [REDACTED] in both the old/new snapshots and the diff. The default masked keywords are:

Customize via .env (comma-separated, case-insensitive substring matching):

Or publish and edit config/audit.php directly.

REST API

All endpoints are prefixed with /api/audit and optionally protected by a token set in AUDIT_TOKEN. Pass the token as either:

• X-Audit-Token: your_token header
• Authorization: Bearer your_token header

If AUDIT_TOKEN is empty, all endpoints are unauthenticated (suitable for internal networks).

Endpoints

GET /api/audit/feed

Paginated activity feed with filtering.

Query parameters:

Response:

GET /api/audit/entry/{id}

Single audit entry by ULID — includes full properties payload.

GET /api/audit/timeline

Chronological activity for a specific user, ordered by most recent.

GET /api/audit/stats

Aggregated statistics for a date range.

Response shape:

GET /api/audit/causers

Distinct causers with activity counts — for populating filter dropdowns. Returns the most recently seen name per causer_id, so renamed users appear only once.

GET /api/audit/export/csv

Exports the filtered log as a .csv file. Accepts the same filter parameters as /feed. Maximum 10,000 rows per export; exports are tracked for alert rate-limiting.

GET /api/audit/export/pdf

Exports a formatted PDF audit trail report. Accepts the same filters as /feed. Powered by dompdf/dompdf.

Alert rule endpoints

Create rule request body:

Alert rules

Alert rules fire when a threshold is exceeded. The package checks patterns synchronously after every AuditEntry is saved.

Default thresholds (configurable via .env)

Custom rules created via the API override these defaults for matching event patterns.

Notification channels

Mailgun (email):

Slack:

Retention pruning

Logs are automatically pruned daily by a scheduled command registered in the service provider. The retention window defaults to 90 days:

Run pruning manually at any time:

Ensure your Laravel scheduler is running:

Database schema

Three tables are created by the package migration:

audit_logs

Indexes on: event, batch_id, ip_address, created_at, and composite morphs indexes on (subject_type, subject_id) and (causer_type, causer_id).

audit_alert_rules

Stores custom threshold rules created via the API.

audit_alert_history

Records every fired alert with the rule name, metric value, threshold breached, and the channels notified.

Configuration reference

After publishing with php artisan vendor:publish --tag=audit-config, your config/audit.php exposes:

Testing

The package ships with a PHPUnit test suite covering DiffService and MaskingService:

Test coverage includes:

• Detecting changed, added, and removed fields in diffs
• Returning an empty diff for identical attribute sets
• Redacting password and token fields (including nested arrays)
• Case-insensitive masking of fields like Password and API_KEY

To run tests against a specific Laravel application using Testbench:

Pro Dashboard

The free package exposes the REST API. To get a full visual interface — activity feed, user timeline, statistics charts, field diff viewer, CSV/PDF export, and alert rule management — pick up the Pro Dashboard:

👉 dineshstack.com/laravel-audit

Built with Next.js 16, React 19, Recharts, and TanStack Query. Self-hosted, dark/light mode, Docker-ready.

Changelog

See CHANGELOG.md for recent changes.

Contributing

Pull requests are welcome. Please open an issue first to discuss significant changes. All contributions must include tests.

Security

If you discover a security vulnerability, please email [email protected] instead of opening a public issue. All disclosures are reviewed within 48 hours.

License

MIT. See LICENSE for the full text.

Author

Dinesh Wijethunga — dineshwijethunga.me