Activitylog Laravel Package

Technical Evaluation

Architecture fit. This package is an integration layer, not a standalone capability: it renders and acts on activity records produced by spatie/laravel-activitylog. Its value is the Filament-facing resource plus restore actions, and its risk profile inherits almost entirely from Spatie's release cadence. That makes it a thin but load-bearing dependency — low code surface, high coupling to a third party's schema. v4.1.0 confirms the maintainer is tracking upstream promptly (v5 support landed in a point release), which is the single most important signal for a package of this shape.

Integration feasibility. Good, with one gating prerequisite that is not delivered by this package. v4.1.0 makes the package tolerant of both Spatie v4 and v5 log shapes:

• Diffs are read from attribute_changes first, with fallback to properties.old / properties.attributes.
• Restore calls withoutLogging() / withChanges() behind method_exists guards.

That dual-path design is the commercially useful part: mixed v4/v5 rows in the same table will render, so a phased migration or partial backfill does not require a maintenance window or a big-bang cutover. The feasibility limiter is that the host application still owns Spatie's own migration (attribute_changes column added, batch_uuid dropped) and the config key rename from subject_returns_soft_deleted_models to include_soft_deleted_subjects.

Technical risk.

• Silent presentation failure. The fallback chain degrades quietly. If neither attribute_changes nor the v4 properties keys are populated, logs render with empty diffs rather than erroring. This is a data-quality bug users will report as "the audit trail is broken," not as an exception — so it needs explicit test coverage per environment, not just a green CI run.
• Config drift. The renamed config key is the highest-probability production surprise. A stale key name will not throw; it will change which records appear (soft-deleted subjects silently dropping out of the audit view). This is a compliance-visible defect in exactly the scenario the feature exists for.
• Irreversibility of the upstream migration. Dropping batch_uuid destroys batch-grouping data. Rolling this package back to 4.0.4 does not restore the column or the data. Rollback is therefore not a clean mitigation for the schema step.
• Permanent shim. The dual-read path is intentional technical debt with no stated removal date. Budget for it in future upgrade planning rather than assuming it is transient.

Key questions.

1. Is this package's config read at runtime from the app's published Spatie config, or from its own? Who owns the key rename in our repo?
2. Does our application rely on batch_uuid anywhere (custom queries, exports, grouping UI) before we drop it?
3. What does the renderer show when both diff sources are absent — blank, placeholder, or silent omission? Is that acceptable to audit/compliance stakeholders?
4. Are we on the Spatie v4 or v5 line today, and what is our committed upgrade date? This package now spans both.
5. Is the method_exists guard a permanent contract or a transitional one? That determines whether we can pin Spatie independently of this package.

Integration Approach

Stack fit. Assumes Laravel + Filament with Spatie activity logging already in place. It is additive: no change to how activity is written, only how it is read and acted on. That keeps the blast radius confined to the admin/audit surface rather than the write path across the domain.

Migration path. Three ordered steps, owned by different parties — this is the sequencing that matters:

1. Spatie upgrade + schema migration (app team): run Spatie's migration, add attribute_changes, drop batch_uuid after confirming no consumers.
2. Config key rename (app team): subject_returns_soft_deleted_models → include_soft_deleted_subjects. Treat as a required step, not optional cleanup.
3. Package upgrade to 4.1.0 (this release): safe to land before, during, or after steps 1–2 given the fallback, though landing it first is preferable — it means the UI is already v5-ready when the schema changes and there is no read-gap.

Compatibility. Bidirectional within the v4/v5 Spatie window, per the dual-path reads. Pin the package version explicitly and record the Spatie range it was certified against, rather than relying on ^ resolution.

Sequencing recommendation. Ship the package upgrade (step 3) as an isolated, low-risk PR ahead of the schema migration, verified against existing v4 data. That decouples "the viewer can read both shapes" from "the data shape changed," so if the schema step causes problems you can attribute them cleanly. Do not bundle the schema migration and the package bump in one change.

Operational Impact

Maintenance. Low code surface, but the maintenance obligation is upstream tracking, and this release demonstrates it is being met. The real cost is the dual-read shim: two rendering paths, two sets of fixtures, indefinitely.

Support. Expect inbound tickets phrased as data loss rather than errors — "history is missing," "changes show blank," "deleted records disappeared." Support runbooks and first-line triage should key on: (a) config key name, (b) presence and population of attribute_changes, (c) whether batch_uuid removal broke an adjacent report.

Scaling. Rendering concerns are the usual Filament/DB ones — pagination and indexing on the activity table as volume grows, and diff rendering cost on wide models with large attribute payloads. The attribute_changes JSON column is the new hot field; index accordingly if the audit view becomes a frequently used screen.

Failure modes.

That last row deserves a decision, not just a note: suppressing the log on restore may be correct hygiene or may be an audit gap, depending on your regime. Get it in writing.

Ramp-up. Minimal for a Laravel/Filament team — hours, not days. The non-obvious cost is domain knowledge: whoever onboards needs to understand the Spatie v4→v5 schema delta and the config rename to debug the failure modes above. Capture that in the upgrade ADR alongside this release, since the next person to touch this will otherwise rediscover it from a blank-diff ticket.