Audit in Controller Flow

Use this approach when data is updated outside Dynamic Record API or when you need explicit snapshot control.

Typical Flow

1. Update business data.
2. Build snapshot payload (getAuditQuery() style).
3. Call AuditLogService::insertAuditLog(...).

Good Use Cases

• Custom transactional flows
• Command/queue-based domain updates
• Legacy controller endpoints

Explicit Admission Context

insertAuditLog and instance log consult optional audit.filter before preparation or queue dispatch. Existing signatures and defaults remain supported. For background work or an explicit actor, use the additive API:

AuditLogService::insertAuditLogWithContext(
    auditLogEventEnum: \Sopheak\Core\Enums\AuditLogEventEnum::UPDATED,
    entityClass: 'invoices',
    queryData: ['id' => $invoiceId, 'old_data' => $before, 'new_data' => $after],
    tenantId: $tenantId,
    context: [
        'actor' => $actor, // Authenticatable or explicit null for system work
        'request' => null,
        'operation' => 'import',
    ],
);

Explicit null actor never falls back to ambient authentication. The tenant argument wins over context. Manual source is manual. Context affects admission only: it does not rewrite stored actor metadata and is never serialized into the audit job. Old subclasses overriding insertAuditLog remain compatible; the new API does not invoke those overrides.

Only mutation events are filtered. False skips, true continues existing no-change/diff processing; errors retain the audit with a sanitized warning. Null/missing config preserves existing behavior. No automatic interface binding discovery occurs when config is null.

Direct processing methods, trait auditing, and direct job dispatch bypass admission. The package's lifecycle listener calls log during the request, so it is evaluated with the originating actor. Only your own ShouldQueue listeners that call log evaluate in a worker with no request; there, call insertAuditLogWithContext() with an explicit actor in its $context array. See full policy contract.