crewli/api/app/Services/FormBuilder/FormSubmissionDuplicateDetector.php

<?php

declare(strict_types=1);

namespace App\Services\FormBuilder;

use App\Enums\FormBuilder\FormSubmissionStatus;
use App\Models\FormBuilder\FormSubmission;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Support\Facades\Log;
use Throwable;

/**
 * Detect whether the same submitter email already has submitted
 * submissions on the same form schema. Used to render an informational
 * hint on the confirmation page — NOT a block. The submission itself
 * proceeds normally regardless of what this returns.
 *
 * Scope: same form_schema_id only. Cross-form detection would leak
 * information about other forms and isn't useful UX.
 *
 * Email source: form_submissions.public_submitter_email (the column
 * populated from the stepper's Contactgegevens step). Not values-based
 * via the schema's binding config — that hypothetical helper doesn't
 * exist in the codebase today and the public flow already has a
 * guaranteed email column. When FORM-05's binding-based extractor
 * lands, this detector can migrate to it without changing its public
 * API.
 *
 * Failure mode: swallow any exception with Log::error and return an
 * empty collection / null. Duplicate detection must never break the
 * submit response.
 */
final class FormSubmissionDuplicateDetector
{
    /**
     * Prior submitted submissions on the same schema from the same
     * email address, ordered oldest-first. Excludes the current
     * submission. Empty when there is no email to compare, when the
     * submission isn't yet persisted, or when detection throws.
     *
     * @return Collection<int, FormSubmission>
     */
    public function findPriorSubmissions(FormSubmission $current): Collection
    {
        try {
            $email = $this->normaliseEmail($current->public_submitter_email);
            if ($email === null) {
                return new Collection;
            }

            if ($current->form_schema_id === null || $current->id === null) {
                return new Collection;
            }

            return FormSubmission::query()
                ->where('form_schema_id', $current->form_schema_id)
                ->where('status', FormSubmissionStatus::SUBMITTED->value)
                ->whereRaw('LOWER(TRIM(public_submitter_email)) = ?', [$email])
                ->where('id', '!=', $current->id)
                ->orderBy('submitted_at')
                ->get();
        } catch (Throwable $e) {
            Log::error('form-builder.duplicate-detector.failed', [
                'submission_id' => $current->id ?? null,
                'message' => $e->getMessage(),
            ]);

            return new Collection;
        }
    }

    /**
     * Shape the detector output for the public submission response.
     * Returns null when no priors exist (the common case) so the
     * resource can render a nullable block.
     *
     * @return array{count: int, first_submitted_at: string}|null
     */
    public function formatForResponse(FormSubmission $current): ?array
    {
        $priors = $this->findPriorSubmissions($current);
        if ($priors->isEmpty()) {
            return null;
        }

        $first = $priors->first();

        return [
            'count' => $priors->count(),
            'first_submitted_at' => optional($first->submitted_at)->toIso8601String() ?? '',
        ];
    }

    private function normaliseEmail(?string $raw): ?string
    {
        if ($raw === null) {
            return null;
        }
        $normalised = strtolower(trim($raw));

        return $normalised === '' ? null : $normalised;
    }
}