Audit Log Laravel Package

Technical Evaluation

Architecture fit: The package fits a Laravel application as an auditable model-change layer: service-provider registration, configuration, migrations, and request/console termination hooks. Release 6.0.0 strengthens the fit for production audit trails by making unflushed records observable and by aligning record commits with the caller’s flush lifecycle. It is best suited to teams that need Laravel-native audit history, not a distributed event-streaming platform.

Integration feasibility: Upgrade is likely straightforward for default Laravel usage. The SubjectLabeller alias is unchanged, so most container-based integrations should continue to work. Direct references to NullSubjectLabeller must move from Infrastructure\Symfony to Recording. The schema change is additive indexes, but it still requires a migration. AuditEntry::fromRecord() is additive and should support detached audit-entry use cases without changing existing flows.

Technical risk: Medium-low overall, but with several items to validate before production. The namespace move is a breaking change for direct class references. RecordReader::actors() changes actor-label semantics from lexicographically greatest to most-recent record, which can alter reports and dashboards. The new indexes on channel, actor_label, and subject_label will improve reader filtering/sorting but may require a careful migration on large audit tables. JSON-invalid values such as NAN, INF, and invalid UTF-8 are now rejected when the event is built or recorded; this is safer than a late flush failure, but it shifts exceptions earlier and may surface payload-quality issues in application paths. The new unflushed-record error log improves observability but does not itself guarantee delivery.

Key questions: Which Laravel and PHP versions are supported by the package’s Composer constraints? Does our application rely on direct NullSubjectLabeller instantiation or extension? Who consumes actor labels in reports, exports, or dashboards, and can they tolerate the new “most recent label” behavior? How large is the audit table, and can the new indexes be applied online without locking risk? Are audit records flushed on all relevant paths: HTTP requests, console commands, queue workers, Octane, and long-running processes? Are domain values ever non-JSON-encodable, and do we want audit rejection to fail the business operation or be handled separately? Do we have retention, partitioning, or archival requirements for the growing audit table?

Integration Approach

Stack fit: Strong fit for Laravel applications already using Eloquent and service providers. The package’s configuration, migrations, and termination hooks align with standard Laravel deployment patterns. Teams with custom audit readers, custom subject labellers, or Symfony integration classes should treat 6.0.0 as a minor-to-moderate integration review rather than a routine patch.

Migration path: Pin 6.0.0 in staging first, update Composer dependencies, publish and review any new migration, and run the schema migration in a controlled environment. Replace direct Infrastructure\Symfony\NullSubjectLabeller references with Recording\NullSubjectLabeller. Keep the SubjectLabeller alias usage unchanged. Clear config and application caches. Test audit capture across HTTP, CLI, queue, and failure/rollback scenarios. For large audit tables, coordinate index creation with database operations and prefer online or phased migration where supported.

Compatibility: Additive APIs and the unchanged SubjectLabeller alias reduce upgrade friction. The two compatibility concerns are direct NullSubjectLabeller references and behavioral changes in RecordReader::actors(). JSON validation is a correctness improvement but can become a compatibility issue if existing domain payloads contain invalid UTF-8 or non-finite numbers. Indexes are schema-compatible but operationally significant on large tables.

Sequencing: First inventory custom references, readers, labellers, and reporting consumers. Then upgrade in staging and run migrations. Next update direct class references and adjust report expectations for actor labels. Then execute lifecycle tests for request termination, console termination, queue workers, and rollback paths. Deploy with canary or limited rollout, monitor for new unflushed-record log entries and JSON-rejection exceptions, and only then promote broadly. If rollback is needed, code rollback is straightforward; indexes are additive and can usually remain, but confirm with the DBA.

Operational Impact

Maintenance: Low for default users, moderate for customized installations. The main maintenance work is the namespace update, schema migration, and documentation of the changed actor-label semantics. The new ADR-linked flush behavior should be understood by the team owning audit compliance.

Support: The new kernel.terminate and console.terminate error logging materially improves supportability because silent audit loss becomes visible. Support runbooks should include what to do when “recorded but never flushed” appears: check termination hooks, queue worker lifecycle, long-running process behavior, and custom audit flush configuration. JSON-rejection errors should be triaged as data-quality or caller-contract issues, not merely package failures.

Scaling: The added indexes on channel, actor_label, and subject_label directly support the reader’s filter and sort paths and should improve read performance as audit volume grows. The migration itself is the primary scaling concern; large tables need a planned index rollout. Audit-table growth still requires retention, archival, or partitioning strategy independent of this release.

Failure modes: Unflushed audit records can still be lost on abnormal termination, but normal termination paths now log the condition. Direct NullSubjectLabeller references will fail until updated. Actor labels may change in reports due to the new most-recent-record rule. Invalid JSON values will fail earlier, potentially surfacing exceptions in application code that previously failed during flush. Index migrations can cause lock contention or deployment delay if applied naively to large tables.

Ramp-up: Low for a standard Laravel team familiar with Composer, migrations, and service providers. The team should spend focused review time on audit lifecycle semantics, actor-label reporting changes, and JSON payload constraints. A short upgrade checklist and support runbook are sufficient for most teams; regulated environments should also review the ADR and confirm audit-loss detection expectations.