breadcrumb-the-shire/lib/Service/Audit/UserLifecycleAuditInterface.php

<?php

namespace MintyPHP\Service\Audit;

/**
 * Core-side contract for recording user lifecycle audit events (deactivation, deletion, restore).
 *
 * Implemented by the audit module's UserLifecycleAuditService when active.
 * Falls back to NullUserLifecycleAudit (no-op) when the audit module is disabled.
 */
interface UserLifecycleAuditInterface
{
    /**
     * @param array<string, mixed> $policy
     * @param array<string, mixed> $targetUser
     */
    public function logDeactivate(
        string $runUuid,
        string $triggerType,
        array $policy,
        ?int $actorUserId,
        array $targetUser,
        string $status = 'success',
        ?string $reasonCode = null
    ): bool;

    /**
     * @param array<string, mixed> $policy
     * @param array<string, mixed> $targetUser
     */
    public function logDeleteWithSnapshot(
        string $runUuid,
        string $triggerType,
        array $policy,
        ?int $actorUserId,
        array $targetUser
    ): int|false;

    /**
     * @param array<string, mixed> $policy
     * @param array<string, mixed> $targetUser
     */
    public function logDeleteFailure(
        string $runUuid,
        string $triggerType,
        array $policy,
        ?int $actorUserId,
        array $targetUser,
        string $reasonCode
    ): bool;

    /**
     * @param array<string, mixed> $policy
     * @param array<string, mixed> $targetUser
     */
    public function logRestore(
        string $runUuid,
        string $triggerType,
        array $policy,
        ?int $actorUserId,
        array $targetUser,
        string $status = 'success',
        ?string $reasonCode = null
    ): bool;

    public function markDeleteEventRestored(int $auditId, int $restoredByUserId, int $restoredUserId): bool;

    public function updateStatus(int $id, string $status, ?string $reasonCode = null): bool;

    public function findDeleteEventForRestore(int $id, bool $forUpdate = false): ?array;

    public function decryptSnapshot(array $event): ?array;
}