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

mxnwire/laravel-audit-log

Audit log viewer and logger layered on top of spatie/laravel-activitylog.

Spatie owns the storage (activity_log table, polymorphic causer/subject, and the activitylog:clean prune command). This package adds:

• An audit_log() helper and AuditLogService that freeze actor identity and request context at write time.
• A built-in viewer UI (filterable table, no JS build step required) protected by a permission gate.
• AuditMetadata / Change value objects for structured before/after diffs in the properties column.

Requirements

Installation

1. Install the package via Composer:

The service provider is auto-discovered — no manual registration needed.

2. Install and run spatie's migration:

If you have not already done so for spatie/laravel-activitylog:

3. Publish the package assets (optional but recommended):

This copies two things:

You only need to publish if you want to customise views or the config file. The package works out of the box without publishing.

Configuration

After publishing, edit config/audit-log.php:

Usage

Logging an audit event

Use the global helper (available automatically — no import needed):

Renamed in 2.0. The helper is now audit_log() and the service is AuditLogService. The old activity_log() helper has been removed — migrate any remaining calls to audit_log().

Or inject the service directly:

Signature

The dotted action maps to spatie's two indexable columns:

The __actor and __request context is merged into spatie's properties JSON column automatically. __actor is the actor snapshot; __request is built from the request_context config (see below):

Configuring __request

The request_context array in config/audit-log.php is the single source of truth for what lands in __request. List the built-in properties you want by name — the package ships resolvers for method, route, url, ip, user_agent, query, and body. query is enabled by default; body is not, since it can carry secrets. To capture anything else, add a keyed entry with your own fn ($request) => mixed resolver (this also overrides a built-in of the same name). Header-sourced values go under the headers group, mapping a property name to the inbound header:

Resolved values land in __request (header values under __request.headers); a null/empty result is dropped, so a request without a given header — or an empty query string — simply omits that property.

Redacting secrets

Logged query and body input is filtered through the redact list before storage, so credentials never reach the log. Matching is case-insensitive and recurses into nested arrays; a matched value becomes "[REDACTED]". The defaults cover common credential fields (password, token, secret, …) — edit the list to fit your app:

To set a value manually (overriding the configured source), pass a field of the same name in the metadata bag — the explicit value always wins and is stored only under __request:

Adding structured metadata

Use AuditMetadata to attach typed field-level detail to a log entry.

Arbitrary fields:

Before/after diff for a specific field:

Stored in properties as:

Auto-diff two arrays (keeps only changed keys):

You can restrict which keys are diffed with the optional third argument:

Fluent chaining:

Viewing logs

The package registers two routes automatically:

Both routes are protected by auth plus a gate callback. The gate config is a closure receiving the authenticated user and returning a boolean; it allows only users whose role is admin by default. Override it in the published config — e.g. fn ($user) => $user?->can('AUDIT_LOGS_ALL') ?? false.

Customisation

Custom viewer layout

To embed the viewer inside your own app shell, set layout in the config to any Blade layout that yields content and script:

Your layout must contain:

Custom route prefix

The named routes (audit-log.index, audit-log.data) follow the prefix automatically.

Custom role resolver

If your app does not use a role or urole attribute directly on the User model:

Custom audit type registry

The viewer's filter dropdowns (log names, events, subject types) come from the class named in the registry config key. By default this is the DB-backed AuditTypeRegistry, which SELECT DISTINCTs the live activity_log table at runtime — zero setup, but it only ever surfaces values that have already been logged.

To serve the options from a fixed vocabulary instead, extend AbstractAuditTypeRegistry, declare your dotted resource.verb actions as constants, and map each resource to its subject model:

Then point the config at it:

The option lists are derived from those constants via reflection, so new RESOURCE_VERB constants enrol automatically.

For full control you can implement AuditTypeRegistryContract directly instead of extending the abstract class — it requires logNames(): array, events(): array, and subjectTypes(): array. The provider binds the contract with bindIf, so an explicit container binding in a service provider still takes precedence over the config value:

Development

Running the tests

The test suite uses Orchestra Testbench and an in-memory SQLite database — no external database or running Laravel app is required.

1. Install dev dependencies (first time only):

2. Run the full suite:

Or call PHPUnit directly:

3. Run a single suite:

4. Run a single test file:

5. Run a single test by name:

Test structure

License

MIT