README

A read-only audit explorer for FilamentPHP with structured diffs, JSON inspection, and record history.

digit7s/filament-audit-toolkit adds a focused, read-only audit UI to Filament 5 applications using digit7s/laravel-audit-toolkit. It does not replace the Laravel package, write audit events, or require a second audit store.

Key Features

Audit Explorer with search, filters, pagination, actor, subject, source, and occurrence context.
Audit Detail with bounded structured before/after changes and developer JSON inspection.
Reusable, subject-scoped Record History relation manager.
Unified, Split, and Fields diff presentations.
Structured JSON Tree View and JSON View with bounded copy support.
Runtime diff-style switching, scoped to the current Livewire component.
Original actor / impersonation attribution with independent authorization.
Panel-specific, deny-by-default authorization callbacks.
Responsive light/dark rendering using package-owned Filament CSS assets.

Requirements

PHP ^8.5
Laravel 13 and digit7s/laravel-audit-toolkit:^0.1
Filament ^5.9
Livewire 4 through Filament

Installation

Install the plugin and its Laravel audit engine from Packagist:

composer require digit7s/filament-audit-toolkit

The Laravel package owns the audit table. Publish its configuration and migrations and migrate before opening the panel:

php artisan vendor:publish --tag=audit-toolkit-config
php artisan vendor:publish --tag=audit-toolkit-migrations
php artisan migrate

Laravel and Filament discover both service providers automatically. Run php artisan filament:assets when publishing Filament assets for a deployed application.

For sibling-checkout development, see CONTRIBUTING.md. Normal consumers do not need path repositories or development aliases.

Panel Plugin Registration

use Digit7s\FilamentAuditToolkit\FilamentAuditToolkitPlugin;

->plugin(
    FilamentAuditToolkitPlugin::make()
        ->authorization(
            viewAny: fn (?object $user): bool => $user?->can('viewAnyAuditEvents') ?? false,
            view: fn ($event, ?object $user): bool => $user?->can('viewAuditEvent') ?? false,
            viewRawValues: fn ($event, ?object $user): bool => $user?->can('viewAuditValues') ?? false,
            viewSubjectHistory: fn ($record, ?object $user): bool => $user?->can('viewAuditHistory', $record) ?? false,
            viewOriginalActor: fn ($event, ?object $user): bool => $user?->can('viewAuditImpersonation', $event) ?? false,
        ),
)

The plugin class is Digit7s\FilamentAuditToolkit\FilamentAuditToolkitPlugin. Its service provider is Digit7s\FilamentAuditToolkit\FilamentAuditServiceProvider.

Authorization

Authorization is deny-by-default and is stored per registered panel. The active panel's guard supplies the callback user, so multiple panels may use different guards and policies. Navigation visibility is not authorization: resource queries, detail routes, raw-value projections, and history mounting enforce the callbacks server-side.

If viewRawValues is omitted, safe value presentation follows view. Safe values have already passed the Laravel package's storage-time privacy filtering; this plugin cannot recover excluded fields.

Audit Explorer

Digit7s\FilamentAuditToolkit\Resources\AuditEventResource provides a paginated, read-only table with event-name search, event/category/date filters, actor and subject references, occurrence timestamps, and optional source, request, correlation, batch, and original-actor columns. Event names and the eye action link only to authorized detail views.

Audit Detail

The detail page is Digit7s\FilamentAuditToolkit\Resources\AuditEventResource\Pages\ViewAuditEvent. It presents event summary, execution context, safe metadata, bounded field changes, and authorized developer details. Long event names wrap safely and exact timestamps are shown in UTC with relative context.

Record History

Add AuditHistoryRelationManager to a resource whose model uses the core package's Auditable concern:

use Digit7s\FilamentAuditToolkit\RelationManagers\AuditHistoryRelationManager;

public static function getRelations(): array
{
    return [AuditHistoryRelationManager::class];
}

The relation is polymorphic, subject-scoped, paginated, and read-only. It shows event, actor, source, timestamp, and an escaped before/after summary. It checks viewSubjectHistory before mounting and still requires viewRawValues for value display.

Structured Diff Viewer

The DiffBuilder and DiffViewerEntry use one bounded representation with three presentations:

unified: compact additions and removals with textual + and − indicators.
split: responsive Before and After columns.
fields: administrator-friendly cards with humanized labels and technical paths.

Nested associative values become deterministic dotted paths. Lists compare by numeric index; move detection is intentionally not attempted. Missing values are [missing], explicit null remains null, and depth, entry, array-size, and display-length limits produce visible omitted/truncated markers.

Structured JSON Viewer

Safe Metadata and authorized Developer Details use the bounded JsonViewerBuilder. Tree View exposes expandable object/array nodes; JSON View shows the same sanitized projection as indented syntax-highlighted JSON. Strings, numbers, booleans, null, empty values, and omission markers retain their type semantics. Copy JSON is available only to an authorized viewer and never includes excluded data.

Diff Configuration and Runtime Switching

Configure global defaults in published config/filament-audit-toolkit.php:

'diff' => [
    'default_style' => 'unified',
    'available_styles' => ['unified', 'split', 'fields'],
    'allow_style_switching' => false,
    'max_depth' => 5,
    'max_entries' => 100,
    'max_value_length' => 2000,
    'max_array_elements' => 100,
],
'json_viewer' => [
    'default_mode' => 'tree',
    'max_depth' => 5,
    'max_entries' => 200,
    'max_value_length' => 2000,
    'allow_copy' => true,
],

Panel-level methods on FilamentAuditToolkitPlugin are:

FilamentAuditToolkitPlugin::make()
    ->diffStyle('split')
    ->availableDiffStyles(['unified', 'split'])
    ->allowDiffStyleSwitching();

Runtime selection is validated against enabled built-in styles, is component-local, and is never persisted. The Audit Detail page and Record History relation expose the native Livewire action only when switching is enabled.

Configuration

The package configuration controls navigation grouping/sort, diff styles and bounds, JSON viewer mode and bounds, and copy support. The plugin does not publish a second database configuration or migration. The Laravel core package remains the source of audit storage and privacy policy.

Security and Read-only Behavior

The plugin provides no edit, delete, bulk-delete, clear-all, restore/revert, retention, or pruning actions. It is a read-only presentation layer for v0.1.0; automated retention and pruning are not available. Future releases may add controlled retention policies, dry-run cleanup, and protected event handling.

Built-in views use escaped Filament/Blade rendering and package-owned assets. Authorization callbacks must be configured for every panel. A passing test suite is not a production security certification, and database-level immutability is not guaranteed by either package.

Troubleshooting

If the audit table is missing, publish the core migration and run php artisan migrate.
If the Explorer is forbidden, configure viewAny and view for the active panel.
If safe or raw values are hidden, configure the appropriate callback; storage-time allowlists cannot be bypassed.
If subject history is forbidden, configure viewSubjectHistory and confirm the host resource authorizes the subject.
If assets are missing after deployment, run php artisan filament:assets.

Related Laravel Core Package

The backend package is digit7s/laravel-audit-toolkit. It works without Filament and provides recording, Eloquent auditing, privacy filtering, attribution context, migrations, and the AuditQuery contract.

Contributing, Security and License

Run composer validate --no-check-publish, composer check-platform-reqs, composer lint, composer analyse, and composer test before submitting changes. See CONTRIBUTING.md, SECURITY.md, and RELEASE_CHECKLIST.md.

MIT licensed. See LICENSE.

digit7s / filament-audit-toolkit

Package info

Security

Statistics