Laravel Activitylog Ui Laravel Package

Technical Evaluation

Architecture fit. The package is a presentation layer, not a logging system. It assumes spatie/laravel-activitylog v5 is already installed, configured, and writing to activity_log, and it reads that table. That boundary is the right one for us: it adds no write path, no new domain model, and no data duplication, so the blast radius of adopting or removing it is a route, a config file, and a handful of Blade views. The one place it reaches past a read-only boundary is an opt-in migration that adds indexes to activity_log — a table Spatie owns, not this package. That single migration is the only structural change we are accepting.

Integration feasibility. Mechanically trivial: one composer require, optional config/views/assets publish, a route prefix, a gate. Critically, there is no front-end build step — Tailwind and Alpine ship as a package-served versioned stylesheet (~6KB over the wire per the v3 notes) and the Play CDN/Chart.js/webfont loads were removed. For a Laravel app with a locked-down Vite/npm pipeline or a strict CSP, that removes the usual integration tax for UI packages.

Technical risk. The gating constraint is version alignment, not code quality: PHP ≥ 8.4, Laravel 12 or 13, Spatie activitylog ≥ 5.0. That is a very narrow slice of the installed base and will disqualify the package outright for most current estates. Secondary risks:

• Maturity vs. churn. 196 stars, 0 dependents, single maintainer, and already two breaking majors (v2 for Spatie v5, v3 for security/correctness). Breaking-major cadence is high relative to adoption.
• Security posture was immature until v3. v3 makes authorization default-on, fixing a default install that served the entire audit log to unauthenticated visitors; it also fixed export ownership, a search-suggestion email exposure, and non-random export job IDs. Adopting only on ≥3.0 is the correct posture — anything earlier is a public audit-log leak.
• Strict validation is a behavior change. Out-of-range/unusable params now return 422 instead of being silently clamped. Anything we script against these endpoints must be written to v3 semantics.
• Optional dependencies. XLSX/PDF silently fall back to CSV/JSON if maatwebsite/excel / barryvdh/laravel-dompdf are absent. Silent degradation will be reported as a defect by users.

Key questions.

• Are we on Laravel 12/13 + PHP 8.4 today, or is that upgrade already funded and dated? (If not, this is a "revisit later," not a decision.)
• Is spatie/laravel-activitylog already on v5 with attribute_changes populated, or are we pre-v5?
• How large is activity_log, and can we obtain a DDL window for the index migration?
• What is our retention policy on activity_log? The UI exposes everything within that window to whoever holds the gate.
• Who is the named internal owner if upstream goes quiet, and is forking acceptable?
• Do we actually need PDF/XLSX export, and do we have a monitored queue worker?

Integration Approach

Stack fit. Only proceed if the version matrix already matches or a platform upgrade to Laravel 12/13 + PHP 8.4 is independently committed. Do not upgrade the platform for this package — treat adoption as a rider on an upgrade we'd do anyway. The package's own value proposition (self-serve audit visibility for non-engineers) is real but not worth a platform migration on its own.

Migration path.

1. Confirm Spatie v5 and the attribute_changes column exist. The UI ships legacy fallbacks that read properties.old / properties.attributes, so no backfill is required for readability — but pre-v5 rows will render under "Custom Properties" rather than "Attribute Changes." Decide explicitly whether that historical inconsistency is acceptable or whether a backfill is in scope.
2. Install to staging against a restored copy of the production activity_log table. This is the only way to size the query and index work honestly.
3. Publish and review config/activitylog-ui.php line by line. Verify authorization.enabled, because v3 flips the default to true for installs that never published the config, while published configs retain their own value. Confirm access.allowed_users / allowed_roles are now actually enforced even when authorization.enabled is false — that combination was previously a no-op.
4. Define the viewActivityLogUi gate in application code rather than relying on the package's email/role defaults.
5. Run the index migration separately from the deploy, in a maintenance window. It locks activity_log while it runs; the upstream benchmark (350ms → 21ms on ~205k rows) tells us this is not optional above roughly six figures.
6. Do not assume route.middleware bypasses auth. In v3 it replaces the base stack only; the security middleware is appended afterward. Mount the UI behind the admin guard.

Compatibility. Beyond the version matrix, the two compatibility surfaces to test are (a) the JSON API contract — clients we write must expect 422 on bad params and anchor_id+anchor_time as a pair on the list endpoint; and (b) export URLs, which are now scoped to the creating user, so any shareable-export workflow we've assumed breaks.

Sequencing. Version verification → staging install with prod data copy → config and gate review → index migration in a window → pilot with a narrow audience (security/compliance/support leads) behind auth → broaden. Do not expose to the general user base before the gate and access lists are proven in the pilot.

Operational Impact

Maintenance. Single maintainer, MIT, zero dependents — there is no downstream ecosystem acting as a compatibility canary. Pin exact versions and read UPGRADING.md before every bump; two breaking majors in roughly a year is the observed cadence. Mitigant: with no build step, the view layer is plain Blade + Alpine, so an internal fork is genuinely tractable if upstream stalls. Budget a named owner either way.

Support. Documentation is hosted off-repo (sadeeq.dev), not in the repository — a third-party availability dependency. No vendor, no SLA, no commercial support path. All support is internal.

Scaling. This is a read-heavy UI against the audit table: paginated list, timeline, analytics aggregation, a search that spans attribute_changes, properties, and description, plus exports. Concretely:

• The index migration is a prerequisite at scale, not an optimization.
• Analytics are cached 1h by default — tune analytics.cache_duration to the freshness the audience actually needs, and expect the first request after each expiry to be slow.
• Search across JSON/text columns will not hold at millions of rows without a dedicated index or external search; scope the UI to a bounded date range or a narrowed causer/subject filter for large tenants.
• Set exports.max_records deliberately and enable exports.queue with a threshold well below the default. A synchronous 10k-row PDF export is a request-timeout and memory incident waiting to happen, and the queue is off by default.

Failure modes.

1. Unauthenticated exposure — the highest-severity failure and one this package has already shipped once. Caused by config drift or someone setting ACTIVITYLOG_UI_AUTHORIZATION=false. Add a startup/config assertion and a periodic unauthenticated-request check.
2. 422 on previously tolerated parameters — dashboards, saved bookmarks, or internal scripts written against v2 break loudly rather than degrading.
3. Export 403 across users — shared export links stop working by design; communicate before rollout.
4. Front-end "JSON parse" errors — per the 2.0.1 fix, these usually mean a non-JSON response, most often an auth redirect returning HTML to an AJAX call. Symptom points at the guard, not the package.
5. Index migration lock contention on a large activity_log during a live deploy.
6. Silent export fallback when optional packages are missing — users report "PDF is broken," actual cause is a missing composer dependency.
7. Schema drift if Spatie ships another major and the column assumptions in the UI lag.

Ramp-up. Near-zero for end users — it is a self-serve interface with filters, saved views, and timeline/table/analytics modes. Low for developers (composer + publish + gate). Moderate for ops (DDL window, queue worker, auth verification). The real ramp-up cost is not learning the tool; it is independently verifying a security posture that upstream only reached in v3, which is work we own regardless of what the README claims.