Nova Action Event Columns Laravel Package

Product Decisions This Supports

• Audit & compliance readiness. Nova already logs actions to action_events, but the default schema can't answer "from where?" or "for which tenant?" This package closes that gap with an ip_address column out of the box and a registry for tenant_id, user_agent, etc. That directly supports SOC 2 / ISO 27001 evidence, GDPR subject-access and breach-investigation requests, and enterprise security questionnaires — often a hard blocker in B2B/enterprise deals.
• Multi-tenant attribution as a product feature. Registering tenant_id turns Nova's activity log into a per-tenant audit trail, which unlocks customer-facing "activity history" screens, tenant-scoped admin views, and per-tenant retention policies — roadmap items that are otherwise blocked on data that was never captured at write time.
• Support-cost reduction (build vs. buy). "Who deleted this record, and when, and from where?" is a recurring escalation. Coverage of every write path — including delete, force-delete, and restore jobs via the mass-insert override — means destructive actions are attributable, not just creates and updates. That shortens incident triage and reduces engineering time pulled into support tickets.
• Data retention as a deliberate policy decision. The action-events:prune command (--days / --hours / --all, with production confirmation) lets you ship a documented retention window instead of an unbounded audit table. This is a storage-cost decision and a GDPR storage-limitation decision, and it's now a config line rather than a custom job.
• Roadmap de-risking on Nova upgrades. Because the columns are additive and config-published, this is a low-coupling way to extend Nova rather than forking its internals. It also surfaces an upgrade forcing function: Nova 4 support is capped at PHP 8.4 / Laravel 11, so any team on PHP 8.5 or Laravel 12+ is implicitly committing to Nova 5.
• Feature-flag style rollout. ip_address capture is toggleable via config, so you can enable it per environment, validate the data quality in staging, and roll to production without a code change.

When to Consider This Package

Adopt when:

• You run Laravel Nova 4 or 5 and already rely on (or intend to rely on) action_events as your operational audit trail.
• You need context Nova doesn't natively store — IP, tenant, user agent, request origin, impersonation flag — and you need it on every action, not just the ones a developer remembered to instrument.
• You have a multi-tenant product where per-tenant audit visibility is a customer requirement.
• You have, or are about to be asked for, a compliance artefact that requires attributable change history with a defined retention period.
• You want buy over build: the alternative is a homegrown trait/hook set that must keep pace with Nova internals on every major release.

Look elsewhere or proceed with caution when:

• You're not on Nova. This is entirely coupled to Nova's action_events model and ActionResource; there is no value outside it.
• You need an audit log that is tamper-evident or immutable. This appends columns to a table your app can still write to and prune. If you need WORM storage, hash-chaining, or a SIEM export as the source of truth, treat this as a convenience layer, not a compliance-grade audit system.
• You're on PHP 8.5 / Laravel 12+ / Nova 4. The Nova 4 path is capped at PHP 8.4 and Laravel 11 — plan the Nova 5 upgrade first.
• Engineering flags the insert() override as unacceptable coupling. Extending Nova's mass-insert path is the clever part and the fragile part; if your team's policy is "no overrides of framework internals," get an explicit exception or scope down to the creating hook only.
• You need high-volume, high-cardinality analytics. This is an audit trail, not an event pipeline. If the goal is product analytics or per-request telemetry, this is the wrong tool.
• Bus-factor risk is unacceptable for a compliance-adjacent dependency. v1.0.0 is a first stable release. The quality signals are genuinely strong (100% line coverage, mutation testing MSI ≥ 80%, PHPStan level 8, CI across both Nova majors), but maturity and maintainer depth are still unproven — worth a maintainer-responsiveness check before it becomes load-bearing for an audit obligation.

How to Pitch It (Stakeholders)

For executives: This is a small, low-cost addition that unblocks enterprise and compliance requirements we currently can't satisfy — specifically, being able to say who changed what, from where, and on behalf of which customer. It also converts Nova's existing activity log into a per-tenant audit trail we can surface to customers, and it lets us enforce a retention window so the audit table doesn't grow unbounded. The alternative is building and permanently maintaining the same capability ourselves against Nova's internals.

For engineering: A first stable release of a Nova extension that adds registered columns to action_events and populates them on every write path — a creating hook for the save-based paths and an insert() override for the mass-insert paths (deletes, force-deletes, restores, custom actions). Configuration is publishable (migration, column-stub migration, config), the built-in ip_address column is behind a config toggle, and a custom ActionResource renders registered columns with sensible read-only defaults. Ships an action-events:prune command with day/hour/all granularity and a production confirmation prompt. Quality posture is above the norm for a v1.0.0: 100% line coverage, mutation-tested (MSI ≥ 80%), PHPStan level 8, Pint, CI on Nova 5 (Laravel 11/12/13, PHP 8.3/8.4) and Nova 4 (Laravel 11, PHP 8.4). Requires PHP ^8.2.

Two things to decide explicitly before we adopt: (1) the insert() override touches Nova's mass-insert internals — we should accept that coupling consciously and pin/monitor Nova versions; (2) if this becomes the basis of a compliance obligation, we need a named owner and a fallback, since it's a single first-stable dependency. If both are acceptable, the recommended path is to enable ip_address in staging first, add tenant_id alongside the tenant rollout, and set the prune window to match our documented retention policy.