Filament Activity Log Laravel Package

Technical Evaluation

Evaluating alizharb/filament-activity-log v2.0.0 as a candidate dependency. Basis: v2.0.0 release notes only — no prior assessment on file and no hands-on spike performed, so findings below are architectural inference plus a spike plan.

Architecture fit. The package is a Filament panel plugin, not a general-purpose audit library. Value is realized only where the audit surface is exposed through Filament resources, widgets, and relation managers. Two consequences:

• If our audit consumers are an API, BI tool, or SIEM, v2 still adds backend value (integrity signatures, retention holds, risk scoring, scoped queries) but the UI investment is stranded. Confirm the consumer before committing.
• It wraps Spatie Laravel Activitylog as the write path, so adoption is really a two-layer decision: Spatie for capture, this package for the control center. If Spatie is already in the stack, marginal cost is guardrails and UI; if not, we are adopting an audit data model, not just a plugin.

Integration feasibility. High. Standard Composer install plus four artisan commands (vendor:publish, migrate, backfill, verify-integrity, doctor). The only nontrivial path is v1 → v2.

Technical risk, highest to lowest:

1. Restore/revert is a write-to-production path. v2 disables destructive actions by default and gates mutations behind authorization, but the capability itself is the risk. Conflict detection and stale-revert blocking reduce blast radius; they do not remove it. This needs a policy decision, not a config flag.
2. HMAC integrity signatures create a key lifecycle. Rotation, environment parity, and unsigned legacy rows are operational failure modes that surface as loud verification failures. No documented rotation procedure in the notes.
3. Tenant scoping is a security control. A misconfigured scope boundary is a cross-tenant data exposure. Requires a negative test in CI, not a smoke test.
4. Backfill on large activity tables. Duration, lock profile, and resumability on a production-sized table are unknown from the notes.
5. Wide compatibility surface (PHP 8.3–8.5, Laravel 12–13, Filament 4–5, Spatie 4–5). Breadth is a good sign, but verify our exact combination is on the tested matrix rather than assuming it.

Key questions for the maintainer / spike:

• Which tenancy model does the scope boundary assume, and how is it configured?
• Where does the HMAC secret live, and how is it rotated without invalidating history?
• Backfill behavior at N million rows: chunked, resumable, lock profile?
• Can restore/revert be disabled at the policy layer, not just hidden in the UI?
• Does export respect scope and redaction, and is export itself audited as data egress?
• Who can place or remove a retention hold, and is that action audited?
• Support model: maintainer count, release cadence, security disclosure channel?
• Does doctor validate our configuration or only package internals?

Integration Approach

Stack fit. Assume Laravel 12 + Filament 4 as the likely pairing; both are explicitly supported. Gating check first: if we are on Filament 3 or Laravel 11, this release does not help us and the evaluation stops.

Migration path from v1. Treat the four-step upgrade as a gated sequence with checkpoints, not a script to run once:

1. Staging install — composer require alizharb/filament-activity-log:^2.0, publish migrations, migrate.
2. Backfill — time it against production-shaped data volume, not a dev seed.
3. Verify integrity — expect failures on pre-v2 rows; decide explicitly whether that is an accepted baseline or requires re-signing.
4. Doctor — capture output as the pre/post configuration diff.

The breaking changes are behavioral, not just schema. Destructive actions off by default, mutations and exports now requiring explicit authorization, and stale reverts blocked means teams relying on v1's permissive behavior lose functionality silently — no exception, no error. Audit existing usage for dependence on those paths and brief admins before deploy.

From scratch. Lower risk. Install, configure tenancy and the signing secret, run doctor, then enable capabilities in order: read-only → export → restore/revert last, or never.

Sequencing:

• Pin the Filament major. Do not let a Filament 5 upgrade arrive transitively while this plugin is mid-rollout.
• Settle the Spatie major first; this package sits on top of it and spans 4 and 5.
• Roll out staging → internal/compliance users → broader admin. Restore/revert is a separate enablement decision with its own approval.

Operational Impact

Maintenance. Active, security-focused major release at 100k+ downloads — a good maintenance signal, since v2's theme is hardening rather than features. The cost is upgrade cadence: every framework major will drag this package along, and defaults that change behavior will keep arriving in minor releases. Budget one upgrade cycle per framework major plus a review of default changes.

Support. Assume single-maintainer risk until verified. Twelve fully translated locales with automated key and placeholder parity tests, plus domain-specific localized exceptions and structured logging, is unusually mature for a package at this tier — evidence of real production use. Still confirm the security disclosure channel and release cadence before dependency-critical adoption.

Scaling.

• Indexed audit metadata, deferred table loading, and scope-safe aggregate caching are the direct answers to large-table performance; they are the main reason to take v2 rather than stay on v1.
• Caching keyed to scope means correctness depends on invalidation firing on every mutation path. Worth a targeted test rather than trust.
• Risk scores are persisted, so they are computed on the write path and are not retroactive without backfill. Confirm the added write overhead is acceptable on hot tables.

Failure modes to plan for:

• Integrity verification failing after secret rotation or an environment mismatch → write the runbook before the first rotation.
• Backfill timing out or locking on a large table → run in a maintenance window, chunked.
• Cross-tenant leakage from a misconfigured scope → negative test in CI.
• Restore applying an unintended state or colliding with concurrent edits → keep disabled; if enabled, require a second approver.
• Silent capability loss post-upgrade → communicate to admins pre-deploy.
• Pruning blocked by retention holds → expected, but without a hold-review cadence the table grows unbounded.
• PII and IP retention in audit records → data governance review. "Sensitive attributes excluded from restore" is not the same as "not stored."

Ramp-up. Low for developers: standard install, four commands, and doctor output as the first debugging step. Moderate for admins: holds, risk tabs, and restore are new surfaces with real consequences. The real prerequisite is a written audit-data policy — who exports, who restores, how long we retain, who reviews holds — before enablement. Without it, the security defaults are features nobody owns. Estimate a 1–2 day staging spike for install and backfill timing plus one policy session before production.

Recommendation. Adopt to staging to validate tenancy mapping, backfill duration, and write-path overhead. Conditions for production: a passing cross-tenant negative test, a documented signing-key rotation runbook, and an explicit decision on restore/revert (default: remain disabled).