Filament Activity Log Laravel Package

Getting Started

Start by treating v2 as a security/audit layer, not just an activity viewer.

1. Install and publish:

   composer require alizharb/filament-activity-log:^2.0
   php artisan vendor:publish --tag=filament-activity-log-migrations
   php artisan migrate
   

2. Run the v2 setup/verification flow:

   php artisan filament-activity-log:backfill
   php artisan filament-activity-log:verify-integrity
   php artisan filament-activity-log:doctor
   

3. Look first at:
   • config/filament-activity-log.php for tenant scoping, authorization, retention, HMAC/integrity, redaction, and risk settings.
   • The published audit metadata migration.
   • The package’s Filament resource/relation manager registration.
   • Policies/gates for mutations and exports.
4. First use case: open the Filament activity resource, confirm tenant filtering, inspect risk badges, and verify that a normal model update appears with correct subject, causer, request ID, IP, and risk score.

For multi-tenant apps, configure the tenant resolver/relationship before exposing the resource. For upgrades from v1, assume the migration, backfill, integrity verification, and doctor commands are mandatory release steps.

Implementation Patterns

• Use package-owned queries as the audit boundary. Rely on the central tenant-aware scope for resources, widgets, filters, exports, timelines, pruning, and mutations. If you add custom widgets or relation managers, keep them inside the same scope rather than writing unscoped Activity queries.
• Authorize explicitly. v2 disables destructive actions by default and requires authorization for mutations and exports. Define policies/gates early, then test with non-admin roles.
• Use investigation filters for incidents. Filter by request ID and IP to reconstruct a request path, then pivot through subject timelines and related activities. Persistent filters/search/sorting make this practical in Filament.
• Use retention holds for investigations/compliance. Place holds on records that must survive pruning. Held records are protected from package pruning; document the release process for removing holds.
• Use restore/revert carefully. v2 blocks stale reverts by default and excludes sensitive/system attributes. Treat restore as a controlled operation: review conflicts, confirm authorization, and log the outcome. Use subject restorers for custom models.
• Extend at the package seams. Add domain-specific audit rules, context collectors, timeline sources, and subject restorers rather than forking resources. Use fluent table callbacks to customize resource and relation-manager tables.
• Integrate risk scoring into operations. Persisted risk scores allow high-risk/critical tabs and filtering. Tune audit rules so risk reflects your domain, then use high-risk tabs for daily review.
• Use diagnostics in CI/ops. Run filament-activity-log:doctor after deploy/config changes and verify-integrity on a schedule. Backfill after migrations that affect audit metadata.
• Performance pattern: keep indexed audit metadata intact, use package pagination/deferred loading, and avoid custom aggregate queries that bypass scope-safe caching/invalidation.
• Localization: 12 locales ship complete. Publish/override translations only when needed; tests enforce key/placeholder parity.

Gotchas and Tips

• v1 to v2 is not just a composer bump. Publish and run the audit metadata migration, then backfill. Existing rows may lack risk scores or integrity signatures until backfilled.
• HMAC verification depends on stable secret configuration. Rotating or misconfiguring the signing secret will make verification fail. Run verify-integrity after config changes and investigate failures rather than ignoring them.
• Tenant context can disappear outside HTTP/Filament requests. Queued jobs, console commands, and exports must establish tenant context or package scopes may return empty/incorrect results. Test these paths.
• Destructive actions are off by default. If restore/revert/delete buttons are missing, check authorization and default security settings before assuming a UI bug.
• Exports are authorized operations. Missing export permissions are a common cause of “export not working.” Also confirm redaction settings for secrets/sensitive attributes.
• Stale revert conflict detection is intentional. Do not bypass it blindly. Surface conflicts to the operator and use subject restorers for custom conflict handling.
• Retention holds override pruning. If records unexpectedly survive pruning, check for active holds. Conversely, do not expect pruning to remove held records.
• Custom queries can break tenant isolation. Any direct Activity query, custom widget, or report must apply the same tenant boundary. Prefer package query APIs.
• Cache invalidation is scope-safe by design. Custom aggregate caches need the same discipline; otherwise dashboards can leak cross-tenant counts.
• Debug with filament-activity-log:doctor first, then structured logs and localized exceptions. The doctor is intended for installation and security diagnostics, not just fresh installs.
• Compatibility matrix: PHP 8.3–8.5, Laravel 12–13, Filament 4–5, Spatie Activitylog 4–5. Pin versions in CI and run PHPStan/Pint/security audit if you extend package internals.