Skip to content

Beautiful Open-Source Form Builder

Add automatic submission retention (#1215)

Julien Nahumaa6baf858c98
diff --git a/api/app/Console/Commands/PurgeExpiredFormSubmissions.php b/api/app/Console/Commands/PurgeExpiredFormSubmissions.php
new file mode 100644
index 000000000..1e2001c30
--- /dev/null
+++ b/api/app/Console/Commands/PurgeExpiredFormSubmissions.php
@@ -0,0 +1,72 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Jobs\Form\PurgeExpiredFormSubmissions as PurgeExpiredFormSubmissionsJob;
+use App\Models\Forms\Form;
+use App\Service\Forms\SubmissionRetentionService;
+use Illuminate\Console\Command;
+use Throwable;
+
+class PurgeExpiredFormSubmissions extends Command
+{
+ protected $signature = 'forms:purge-expired-submissions
+ {--form= : Only process a specific form ID}
+ {--dry-run : Count expired submissions without deleting them}';
+
+ protected $description = 'Permanently delete form submissions past their configured retention period';
+
+ public function handle(SubmissionRetentionService $retentionService): int
+ {
+ $query = Form::withTrashed()
+ ->whereNotNull('submission_retention_value')
+ ->whereNotNull('submission_retention_unit');
+
+ if ($formId = $this->option('form')) {
+ $query->whereKey($formId);
+ }
+
+ $dryRun = (bool) $this->option('dry-run');
+ $processedForms = 0;
+ $expiredSubmissions = 0;
+ $failedForms = 0;
+
+ $query->lazyById(100)->each(function (Form $form) use (
+ $retentionService,
+ $dryRun,
+ &$processedForms,
+ &$expiredSubmissions,
+ &$failedForms
+ ) {
+ $processedForms++;
+
+ try {
+ if (!$dryRun) {
+ PurgeExpiredFormSubmissionsJob::dispatch($form->id);
+ $this->line("Form {$form->id}: purge job dispatched.");
+
+ return;
+ }
+
+ $count = $retentionService->countExpired($form);
+
+ $expiredSubmissions += $count;
+
+ if ($count > 0) {
+ $this->line("Form {$form->id}: would delete {$count} expired submission(s).");
+ }
+ } catch (Throwable $exception) {
+ $failedForms++;
+ report($exception);
+ $this->error("Form {$form->id}: purge failed; remaining forms will still be processed.");
+ }
+ });
+
+ $summary = $dryRun
+ ? "{$expiredSubmissions} submission(s) would be deleted"
+ : 'purge jobs dispatched';
+ $this->info("Processed {$processedForms} form(s); {$summary}; {$failedForms} form(s) failed.");
+
+ return $failedForms === 0 ? Command::SUCCESS : Command::FAILURE;
+ }
+}
diff --git a/api/app/Console/Commands/RetryPendingSubmissionFileDeletions.php b/api/app/Console/Commands/RetryPendingSubmissionFileDeletions.php
new file mode 100644
index 000000000..d58d7fb8b
--- /dev/null
+++ b/api/app/Console/Commands/RetryPendingSubmissionFileDeletions.php
@@ -0,0 +1,63 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Jobs\Form\DeletePendingSubmissionFile;
+use App\Models\Forms\FormSubmissionFileDeletion;
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\DB;
+use Throwable;
+
+class RetryPendingSubmissionFileDeletions extends Command
+{
+ protected $signature = 'forms:retry-pending-submission-file-deletions {--limit=1000}';
+
+ protected $description = 'Redispatch pending form submission file deletions';
+
+ public function handle(): int
+ {
+ $limit = max(1, min((int) $this->option('limit'), 10000));
+ $failed = 0;
+
+ $deletionIds = DB::transaction(function () use ($limit) {
+ $ids = FormSubmissionFileDeletion::query()
+ ->where('next_attempt_at', '<=', now())
+ ->oldest('next_attempt_at')
+ ->oldest('id')
+ ->lockForUpdate()
+ ->limit($limit)
+ ->pluck('id');
+
+ if ($ids->isNotEmpty()) {
+ FormSubmissionFileDeletion::query()
+ ->whereKey($ids)
+ ->update(['next_attempt_at' => now()->addMinutes(15)]);
+ }
+
+ return $ids;
+ });
+
+ $deletionIds
+ ->each(function (int $deletionId) use (&$failed) {
+ try {
+ DeletePendingSubmissionFile::dispatch($deletionId);
+ } catch (Throwable $exception) {
+ $failed++;
+ report($exception);
+
+ try {
+ FormSubmissionFileDeletion::query()
+ ->whereKey($deletionId)
+ ->update(['next_attempt_at' => now()]);
+ } catch (Throwable $resetException) {
+ report($resetException);
+ }
+ }
+ });
+
+ $claimed = $deletionIds->count();
+ $this->info("Claimed {$claimed} pending file deletion(s); {$failed} dispatch attempt(s) failed.");
+
+ return $failed === 0 ? Command::SUCCESS : Command::FAILURE;
+ }
+}
diff --git a/api/app/Console/Kernel.php b/api/app/Console/Kernel.php
index edb7e48a1..0550cd828 100644
--- a/api/app/Console/Kernel.php
+++ b/api/app/Console/Kernel.php
@@ -24,6 +24,8 @@ class Kernel extends ConsoleKernel
protected function schedule(Schedule $schedule)
{
$schedule->command('forms:database-cleanup')->hourly();
+ $schedule->command('forms:purge-expired-submissions')->hourly()->withoutOverlapping();
+ $schedule->command('forms:retry-pending-submission-file-deletions')->everyFifteenMinutes()->withoutOverlapping();
$schedule->command('forms:integration-events-cleanup')->daily();
if (config('app.self_hosted')) {
$schedule->command('app:scheduler-status --mode=record')->everyMinute();
diff --git a/api/app/Events/Models/FormSubmissionSaved.php b/api/app/Events/Models/FormSubmissionSaved.php
new file mode 100644
index 000000000..f092454cd
--- /dev/null
+++ b/api/app/Events/Models/FormSubmissionSaved.php
@@ -0,0 +1,17 @@
+<?php
+
+namespace App\Events\Models;
+
+use App\Models\Forms\FormSubmission;
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+
+class FormSubmissionSaved
+{
+ use Dispatchable;
+ use SerializesModels;
+
+ public function __construct(public FormSubmission $submission)
+ {
+ }
+}
diff --git a/api/app/Events/Models/FormSubmissionUpdating.php b/api/app/Events/Models/FormSubmissionUpdating.php
new file mode 100644
index 000000000..ae8f8bfbf
--- /dev/null
+++ b/api/app/Events/Models/FormSubmissionUpdating.php
@@ -0,0 +1,17 @@
+<?php
+
+namespace App\Events\Models;
+
+use App\Models\Forms\FormSubmission;
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+
+class FormSubmissionUpdating
+{
+ use Dispatchable;
+ use SerializesModels;
+
+ public function __construct(public FormSubmission $submission)
+ {
+ }
+}
diff --git a/api/app/Http/Controllers/Forms/FormSubmissionController.php b/api/app/Http/Controllers/Forms/FormSubmissionController.php
index caa3cac91..1a3f75d86 100644
--- a/api/app/Http/Controllers/Forms/FormSubmissionController.php
+++ b/api/app/Http/Controllers/Forms/FormSubmissionController.php
@@ -13,6 +13,7 @@ use App\Jobs\Form\ExportFormSubmissionsJob;
use App\Models\Forms\Form;
use App\Models\Forms\FormSubmission;
use App\Service\Forms\FormExportService;
+use App\Service\Forms\DeleteFormSubmission;
use App\Service\Storage\FileUploadPathService;
use App\Service\Storage\FilenameUrlEncoder;
use Illuminate\Support\Facades\Storage;
@@ -213,19 +214,20 @@ class FormSubmissionController extends Controller
);
}
- public function destroy(Form $form, $submission_id)
+ public function destroy(Form $form, $submission_id, DeleteFormSubmission $deleteSubmission)
{
$this->authorize('delete', $form);
- $submission = $form->submissions()->where('id', $submission_id)->firstOrFail();
- $submission->delete();
+ if (!$deleteSubmission->execute($form, (int) $submission_id)) {
+ abort(404);
+ }
return $this->success([
'message' => 'Record successfully removed.',
]);
}
- public function destroyMulti(Request $request, Form $form)
+ public function destroyMulti(Request $request, Form $form, DeleteFormSubmission $deleteSubmission)
{
$request->validate([
'submissionIds' => 'required|array',
@@ -238,14 +240,7 @@ class FormSubmissionController extends Controller
$this->authorize('delete', $form);
- $submissionIds = $request->submissionIds;
- $form->submissions()
- ->whereIn('id', $submissionIds)
- ->chunk(100, function ($submissions) {
- foreach ($submissions as $submission) {
- $submission->delete();
- }
- });
+ $deleteSubmission->executeMany($form, $request->submissionIds);
return $this->success([
'message' => 'Records successfully removed.',
diff --git a/api/app/Http/Requests/UserFormRequest.php b/api/app/Http/Requests/UserFormRequest.php
index 1d5a26d7e..fc8f96ab4 100644
--- a/api/app/Http/Requests/UserFormRequest.php
+++ b/api/app/Http/Requests/UserFormRequest.php
@@ -218,6 +218,18 @@ abstract class UserFormRequest extends \Illuminate\Foundation\Http\FormRequest
'auto_focus' => 'boolean',
'enable_partial_submissions' => 'boolean',
'enable_ip_tracking' => 'boolean',
+ 'submission_retention_value' => [
+ 'nullable',
+ 'integer',
+ 'min:1',
+ 'max:3650',
+ 'required_with:submission_retention_unit',
+ ],
+ 'submission_retention_unit' => [
+ 'nullable',
+ Rule::in(Form::SUBMISSION_RETENTION_UNITS),
+ 'required_with:submission_retention_value',
+ ],
// Properties - Single-pass validation for performance
// Replaces ~35 wildcard rules (properties.*) with one efficient rule
diff --git a/api/app/Http/Resources/FormResource.php b/api/app/Http/Resources/FormResource.php
index c18e1db8c..807485603 100644
--- a/api/app/Http/Resources/FormResource.php
+++ b/api/app/Http/Resources/FormResource.php
@@ -42,6 +42,8 @@ class FormResource extends JsonResource
'removed_properties' => $this->removed_properties,
'last_edited_human' => $this->updated_at?->diffForHumans(),
'seo_meta' => $this->seo_meta,
+ 'submission_retention_value' => $this->submission_retention_value,
+ 'submission_retention_unit' => $this->submission_retention_unit,
];
if ($this->userIsReadonly()) {
diff --git a/api/app/Jobs/Form/DeletePendingSubmissionFile.php b/api/app/Jobs/Form/DeletePendingSubmissionFile.php
new file mode 100644
index 000000000..91c4cc70d
--- /dev/null
+++ b/api/app/Jobs/Form/DeletePendingSubmissionFile.php
@@ -0,0 +1,76 @@
+<?php
+
+namespace App\Jobs\Form;
+
+use App\Models\Forms\FormSubmissionFileDeletion;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldBeUnique;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\Middleware\WithoutOverlapping;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\Storage;
+use RuntimeException;
+use Throwable;
+
+class DeletePendingSubmissionFile implements ShouldBeUnique, ShouldQueue
+{
+ use Dispatchable;
+ use InteractsWithQueue;
+ use Queueable;
+ use SerializesModels;
+
+ public int $tries = 5;
+
+ public int $timeout = 120;
+
+ public int $uniqueFor = 7200;
+
+ public function __construct(public int $deletionId)
+ {
+ }
+
+ public function handle(): void
+ {
+ $deletion = FormSubmissionFileDeletion::find($this->deletionId);
+
+ if (!$deletion) {
+ return;
+ }
+
+ try {
+ if (Storage::exists($deletion->path) && !Storage::delete($deletion->path)) {
+ throw new RuntimeException("Unable to delete submission file at {$deletion->path}.");
+ }
+
+ $deletion->delete();
+ } catch (Throwable $exception) {
+ $deletion->forceFill([
+ 'attempts' => $deletion->attempts + 1,
+ 'last_error' => $exception->getMessage(),
+ ])->save();
+
+ throw $exception;
+ }
+ }
+
+ public function middleware(): array
+ {
+ return [
+ (new WithoutOverlapping("submission-file-deletion:{$this->deletionId}"))
+ ->releaseAfter(60)
+ ->expireAfter(300),
+ ];
+ }
+
+ public function uniqueId(): string
+ {
+ return (string) $this->deletionId;
+ }
+
+ public function backoff(): array
+ {
+ return [60, 300, 900, 3600];
+ }
+}
diff --git a/api/app/Jobs/Form/PurgeExpiredFormSubmissions.php b/api/app/Jobs/Form/PurgeExpiredFormSubmissions.php
new file mode 100644
index 000000000..2621c4728
--- /dev/null
+++ b/api/app/Jobs/Form/PurgeExpiredFormSubmissions.php
@@ -0,0 +1,69 @@
+<?php
+
+namespace App\Jobs\Form;
+
+use App\Models\Forms\Form;
+use App\Service\Forms\SubmissionRetentionService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldBeUnique;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\Middleware\WithoutOverlapping;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\Log;
+
+class PurgeExpiredFormSubmissions implements ShouldBeUnique, ShouldQueue
+{
+ use Dispatchable;
+ use InteractsWithQueue;
+ use Queueable;
+ use SerializesModels;
+
+ public int $tries = 3;
+
+ public int $timeout = 3600;
+
+ public int $uniqueFor = 3600;
+
+ public function __construct(public int $formId)
+ {
+ }
+
+ public function handle(SubmissionRetentionService $retentionService): void
+ {
+ $form = Form::withTrashed()->find($this->formId);
+
+ if (!$form || !$form->submission_retention_value || !$form->submission_retention_unit) {
+ return;
+ }
+
+ $deleted = $retentionService->purge($form);
+
+ if ($deleted > 0) {
+ Log::info('Expired form submissions purged', [
+ 'form_id' => $form->id,
+ 'deleted_submissions' => $deleted,
+ ]);
+ }
+ }
+
+ public function middleware(): array
+ {
+ return [
+ (new WithoutOverlapping("submission-retention:{$this->formId}"))
+ ->releaseAfter(300)
+ ->expireAfter(3900),
+ ];
+ }
+
+ public function uniqueId(): string
+ {
+ return (string) $this->formId;
+ }
+
+ public function backoff(): array
+ {
+ return [300, 900];
+ }
+}
diff --git a/api/app/Listeners/Forms/DeleteFormSubmissionFiles.php b/api/app/Listeners/Forms/DeleteFormSubmissionFiles.php
index 97512b921..76214019a 100644
--- a/api/app/Listeners/Forms/DeleteFormSubmissionFiles.php
+++ b/api/app/Listeners/Forms/DeleteFormSubmissionFiles.php
@@ -3,50 +3,16 @@
namespace App\Listeners\Forms;
use App\Events\Models\FormSubmissionDeleting;
-use App\Service\Storage\FileUploadPathService;
-use Illuminate\Support\Facades\Storage;
+use App\Service\Forms\StageFormSubmissionFileDeletions;
class DeleteFormSubmissionFiles
{
- public function handle(FormSubmissionDeleting $event): void
+ public function __construct(private StageFormSubmissionFileDeletions $stageFileDeletions)
{
- $submission = $event->submission;
- $data = $submission->data;
-
- if (empty($data)) {
- return;
- }
-
- $fileFieldIds = collect($submission->form->properties)
- ->filter(function ($property) {
- return in_array($property['type'], ['files', 'signature']) ||
- ($property['type'] === 'url' && ($property['file_upload'] ?? false));
- })
- ->pluck('id')
- ->all();
-
- foreach ($data as $key => $value) {
- if (!$value || !in_array($key, $fileFieldIds)) {
- continue;
- }
-
- if (is_array($value)) {
- foreach ($value as $file) {
- if (is_string($file)) {
- $this->deleteFile($submission->form->id, $file);
- }
- }
- } elseif (is_string($value)) {
- $this->deleteFile($submission->form->id, $value);
- }
- }
}
- private function deleteFile(int|string $formId, string $fileName): void
+ public function handle(FormSubmissionDeleting $event): void
{
- $path = FileUploadPathService::getFileUploadPath($formId, urldecode($fileName));
- if (Storage::exists($path)) {
- Storage::delete($path);
- }
+ $this->stageFileDeletions->execute($event->submission);
}
}
diff --git a/api/app/Listeners/Forms/TrackFormSubmissionFiles.php b/api/app/Listeners/Forms/TrackFormSubmissionFiles.php
new file mode 100644
index 000000000..fa70b990a
--- /dev/null
+++ b/api/app/Listeners/Forms/TrackFormSubmissionFiles.php
@@ -0,0 +1,18 @@
+<?php
+
+namespace App\Listeners\Forms;
+
+use App\Events\Models\FormSubmissionSaved;
+use App\Service\Forms\SubmissionFileRegistryService;
+
+class TrackFormSubmissionFiles
+{
+ public function __construct(private SubmissionFileRegistryService $fileRegistry)
+ {
+ }
+
+ public function handle(FormSubmissionSaved $event): void
+ {
+ $this->fileRegistry->track($event->submission, $event->submission->data ?? []);
+ }
+}
diff --git a/api/app/Listeners/Forms/TrackOriginalFormSubmissionFiles.php b/api/app/Listeners/Forms/TrackOriginalFormSubmissionFiles.php
new file mode 100644
index 000000000..05666b936
--- /dev/null
+++ b/api/app/Listeners/Forms/TrackOriginalFormSubmissionFiles.php
@@ -0,0 +1,26 @@
+<?php
+
+namespace App\Listeners\Forms;
+
+use App\Events\Models\FormSubmissionUpdating;
+use App\Service\Forms\SubmissionFileRegistryService;
+
+class TrackOriginalFormSubmissionFiles
+{
+ public function __construct(private SubmissionFileRegistryService $fileRegistry)
+ {
+ }
+
+ public function handle(FormSubmissionUpdating $event): void
+ {
+ $originalData = $event->submission->getRawOriginal('data');
+
+ if (is_string($originalData)) {
+ $originalData = json_decode($originalData, true);
+ }
+
+ if (is_array($originalData)) {
+ $this->fileRegistry->track($event->submission, $originalData);
+ }
+ }
+}
diff --git a/api/app/Models/Forms/Form.php b/api/app/Models/Forms/Form.php
index 07cc8953a..e4f347fbe 100644
--- a/api/app/Models/Forms/Form.php
+++ b/api/app/Models/Forms/Form.php
@@ -64,6 +64,8 @@ class Form extends Model implements CachableAttributes, VersionableNestedDiff
public const VISIBILITY = ['public', 'draft', 'closed'];
+ public const SUBMISSION_RETENTION_UNITS = ['day', 'week', 'month', 'year'];
+
public const LANGUAGES = [
'ar',
'bn',
@@ -162,6 +164,8 @@ class Form extends Model implements CachableAttributes, VersionableNestedDiff
'auto_focus',
'enable_partial_submissions',
'enable_ip_tracking',
+ 'submission_retention_value',
+ 'submission_retention_unit',
// Security & Privacy
'can_be_indexed',
@@ -188,6 +192,7 @@ class Form extends Model implements CachableAttributes, VersionableNestedDiff
'translations' => 'array',
'enable_partial_submissions' => 'boolean',
'enable_ip_tracking' => 'boolean',
+ 'submission_retention_value' => 'integer',
'auto_save' => 'boolean',
'pdf_download_enabled' => 'boolean',
'clear_empty_fields_on_update' => 'boolean',
@@ -208,6 +213,8 @@ class Form extends Model implements CachableAttributes, VersionableNestedDiff
'password',
'tags',
'removed_properties',
+ 'submission_retention_value',
+ 'submission_retention_unit',
];
protected $cachableAttributes = [
diff --git a/api/app/Models/Forms/FormSubmission.php b/api/app/Models/Forms/FormSubmission.php
index e1afffcfc..7ad1f79c8 100644
--- a/api/app/Models/Forms/FormSubmission.php
+++ b/api/app/Models/Forms/FormSubmission.php
@@ -3,6 +3,8 @@
namespace App\Models\Forms;
use App\Events\Models\FormSubmissionDeleting;
+use App\Events\Models\FormSubmissionSaved;
+use App\Events\Models\FormSubmissionUpdating;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use App\Models\Version;
@@ -50,6 +52,8 @@ class FormSubmission extends Model implements VersionableNestedDiff
*/
protected $dispatchesEvents = [
'deleting' => FormSubmissionDeleting::class,
+ 'saved' => FormSubmissionSaved::class,
+ 'updating' => FormSubmissionUpdating::class,
];
/**
@@ -60,6 +64,11 @@ class FormSubmission extends Model implements VersionableNestedDiff
return $this->belongsTo(Form::class);
}
+ public function storedFiles()
+ {
+ return $this->hasMany(FormSubmissionFile::class);
+ }
+
public function getVersionNestedDiffFields(): array
{
return ['data'];
diff --git a/api/app/Models/Forms/FormSubmissionFile.php b/api/app/Models/Forms/FormSubmissionFile.php
new file mode 100644
index 000000000..02bc4eef0
--- /dev/null
+++ b/api/app/Models/Forms/FormSubmissionFile.php
@@ -0,0 +1,14 @@
+<?php
+
+namespace App\Models\Forms;
+
+use Illuminate\Database\Eloquent\Model;
+
+class FormSubmissionFile extends Model
+{
+ protected $fillable = [
+ 'form_submission_id',
+ 'path',
+ 'path_hash',
+ ];
+}
diff --git a/api/app/Models/Forms/FormSubmissionFileDeletion.php b/api/app/Models/Forms/FormSubmissionFileDeletion.php
new file mode 100644
index 000000000..55a55ef63
--- /dev/null
+++ b/api/app/Models/Forms/FormSubmissionFileDeletion.php
@@ -0,0 +1,23 @@
+<?php
+
+namespace App\Models\Forms;
+
+use Illuminate\Database\Eloquent\Model;
+
+class FormSubmissionFileDeletion extends Model
+{
+ protected $fillable = [
+ 'path',
+ 'attempts',
+ 'last_error',
+ 'next_attempt_at',
+ ];
+
+ protected function casts(): array
+ {
+ return [
+ 'attempts' => 'integer',
+ 'next_attempt_at' => 'datetime',
+ ];
+ }
+}
diff --git a/api/app/Providers/EventServiceProvider.php b/api/app/Providers/EventServiceProvider.php
index 858f1ce74..fa31572f9 100644
--- a/api/app/Providers/EventServiceProvider.php
+++ b/api/app/Providers/EventServiceProvider.php
@@ -6,6 +6,8 @@ use App\Events\Billing\SubscriptionCreated;
use App\Events\Billing\SubscriptionUpdated;
use App\Events\Forms\FormSubmitted;
use App\Events\Models\FormSubmissionDeleting;
+use App\Events\Models\FormSubmissionSaved;
+use App\Events\Models\FormSubmissionUpdating;
use App\Events\Forms\FormSaved;
use App\Events\Models\FormCreated;
use App\Events\Models\FormIntegrationCreated;
@@ -20,6 +22,8 @@ use App\Listeners\Forms\FormIntegrationCreatedHandler;
use App\Listeners\Forms\FormIntegrationsEventListener;
use App\Listeners\Forms\NotifyFormSubmission;
use App\Listeners\Forms\DeleteFormSubmissionFiles;
+use App\Listeners\Forms\TrackFormSubmissionFiles;
+use App\Listeners\Forms\TrackOriginalFormSubmissionFiles;
use App\Listeners\Forms\FormSpamCheckListener;
use App\Listeners\Integration\FormIntegrationSpamCheckListener;
use Illuminate\Auth\Events\Registered;
@@ -50,6 +54,12 @@ class EventServiceProvider extends ServiceProvider
FormSubmissionDeleting::class => [
DeleteFormSubmissionFiles::class,
],
+ FormSubmissionSaved::class => [
+ TrackFormSubmissionFiles::class,
+ ],
+ FormSubmissionUpdating::class => [
+ TrackOriginalFormSubmissionFiles::class,
+ ],
FormIntegrationCreated::class => [
FormIntegrationCreatedHandler::class,
],
diff --git a/api/app/Service/Forms/DeleteFormSubmission.php b/api/app/Service/Forms/DeleteFormSubmission.php
new file mode 100644
index 000000000..2681e049c
--- /dev/null
+++ b/api/app/Service/Forms/DeleteFormSubmission.php
@@ -0,0 +1,93 @@
+<?php
+
+namespace App\Service\Forms;
+
+use App\Models\Forms\Form;
+use App\Models\Forms\FormSubmission;
+use App\Models\Version;
+use Carbon\CarbonInterface;
+use Illuminate\Support\Facades\DB;
+use RuntimeException;
+use Throwable;
+
+class DeleteFormSubmission
+{
+ public function __construct(private FormSummaryService $summaryService)
+ {
+ }
+
+ public function execute(
+ Form $form,
+ int $submissionId,
+ ?CarbonInterface $updatedBefore = null,
+ bool $invalidateCaches = true
+ ): bool {
+ $deleted = DB::transaction(function () use ($form, $submissionId, $updatedBefore) {
+ $query = $form->submissions()->whereKey($submissionId);
+
+ if ($updatedBefore) {
+ $query->where('updated_at', '<=', $updatedBefore);
+ }
+
+ $submission = $query->lockForUpdate()->first();
+
+ if (!$submission) {
+ return false;
+ }
+
+ $submission->setRelation('form', $form);
+
+ if (!$submission->delete()) {
+ throw new RuntimeException("Unable to delete form submission {$submission->id}.");
+ }
+
+ $submission->storedFiles()->delete();
+
+ Version::query()
+ ->where('versionable_type', FormSubmission::class)
+ ->where('versionable_id', (string) $submission->id)
+ ->delete();
+
+ return true;
+ });
+
+ if ($deleted && $invalidateCaches) {
+ $this->invalidateCachesSafely($form);
+ }
+
+ return $deleted;
+ }
+
+ public function executeMany(
+ Form $form,
+ iterable $submissionIds,
+ ?CarbonInterface $updatedBefore = null
+ ): int {
+ $deleted = 0;
+
+ try {
+ foreach ($submissionIds as $submissionId) {
+ if ($this->execute($form, (int) $submissionId, $updatedBefore, false)) {
+ $deleted++;
+ }
+ }
+ } finally {
+ if ($deleted > 0) {
+ $this->invalidateCachesSafely($form);
+ }
+ }
+
+ return $deleted;
+ }
+
+ private function invalidateCachesSafely(Form $form): void
+ {
+ try {
+ $form->forget('submissions_count');
+ $form->workspace?->forget('submissions_count');
+ $this->summaryService->clearFormSummaryCache($form);
+ } catch (Throwable $exception) {
+ report($exception);
+ }
+ }
+}
diff --git a/api/app/Service/Forms/StageFormSubmissionFileDeletions.php b/api/app/Service/Forms/StageFormSubmissionFileDeletions.php
new file mode 100644
index 000000000..3cbfe16d3
--- /dev/null
+++ b/api/app/Service/Forms/StageFormSubmissionFileDeletions.php
@@ -0,0 +1,72 @@
+<?php
+
+namespace App\Service\Forms;
+
+use App\Jobs\Form\DeletePendingSubmissionFile;
+use App\Models\Forms\FormSubmission;
+use App\Models\Forms\FormSubmissionFileDeletion;
+use App\Models\Version;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\DB;
+use Throwable;
+
+class StageFormSubmissionFileDeletions
+{
+ public function __construct(private SubmissionFilePathService $filePathService)
+ {
+ }
+
+ public function execute(FormSubmission $submission): void
+ {
+ foreach ($this->filePaths($submission) as $path) {
+ $deletion = FormSubmissionFileDeletion::create([
+ 'path' => $path,
+ 'next_attempt_at' => now(),
+ ]);
+
+ DB::afterCommit(function () use ($deletion) {
+ try {
+ $deletion->forceFill([
+ 'next_attempt_at' => now()->addMinutes(15),
+ ])->save();
+ DeletePendingSubmissionFile::dispatch($deletion->id);
+ } catch (Throwable $exception) {
+ report($exception);
+
+ try {
+ $deletion->forceFill(['next_attempt_at' => now()])->save();
+ } catch (Throwable $resetException) {
+ report($resetException);
+ }
+ }
+ });
+ }
+ }
+
+ private function filePaths(FormSubmission $submission): array
+ {
+ return collect($submission->storedFiles()->pluck('path'))
+ ->concat(
+ $this->dataSnapshots($submission)
+ ->flatMap(fn (array $data) => $this->filePathService->fromData(
+ $submission->form,
+ $data
+ ))
+ )
+ ->unique()
+ ->values()
+ ->all();
+ }
+
+ private function dataSnapshots(FormSubmission $submission): Collection
+ {
+ return collect([$submission->data])
+ ->concat(
+ $submission->versions()
+ ->get()
+ ->map(fn (Version $version) => $version->getModel()->data)
+ )
+ ->filter(fn ($data) => is_array($data))
+ ->values();
+ }
+}
diff --git a/api/app/Service/Forms/SubmissionFilePathService.php b/api/app/Service/Forms/SubmissionFilePathService.php
new file mode 100644
index 000000000..5187e2d3a
--- /dev/null
+++ b/api/app/Service/Forms/SubmissionFilePathService.php
@@ -0,0 +1,37 @@
+<?php
+
+namespace App\Service\Forms;
+
+use App\Models\Forms\Form;
+use App\Service\Storage\FileUploadPathService;
+
+class SubmissionFilePathService
+{
+ public function fromData(Form $form, array $data): array
+ {
+ $fileFieldIds = collect($form->properties)
+ ->concat(collect($form->removed_properties))
+ ->filter(function ($property) {
+ $type = $property['type'] ?? null;
+
+ return in_array($type, ['files', 'signature'], true)
+ || ($type === 'url' && ($property['file_upload'] ?? false));
+ })
+ ->pluck('id')
+ ->filter()
+ ->map(fn ($id) => (string) $id)
+ ->all();
+
+ return collect($data)
+ ->filter(fn ($value, $key) => $value && in_array((string) $key, $fileFieldIds, true))
+ ->flatMap(fn ($value) => is_array($value) ? $value : [$value])
+ ->filter(fn ($fileName) => is_string($fileName) && $fileName !== '')
+ ->map(fn (string $fileName) => FileUploadPathService::getFileUploadPath(
+ $form->id,
+ urldecode($fileName)
+ ))
+ ->unique()
+ ->values()
+ ->all();
+ }
+}
diff --git a/api/app/Service/Forms/SubmissionFileRegistryService.php b/api/app/Service/Forms/SubmissionFileRegistryService.php
new file mode 100644
index 000000000..ee268c5b0
--- /dev/null
+++ b/api/app/Service/Forms/SubmissionFileRegistryService.php
@@ -0,0 +1,31 @@
+<?php
+
+namespace App\Service\Forms;
+
+use App\Models\Forms\FormSubmission;
+use App\Models\Forms\FormSubmissionFile;
+
+class SubmissionFileRegistryService
+{
+ public function __construct(private SubmissionFilePathService $filePathService)
+ {
+ }
+
+ public function track(FormSubmission $submission, array $data): void
+ {
+ $now = now();
+ $rows = collect($this->filePathService->fromData($submission->form, $data))
+ ->map(fn (string $path) => [
+ 'form_submission_id' => $submission->id,
+ 'path' => $path,
+ 'path_hash' => hash('sha256', $path),
+ 'created_at' => $now,
+ 'updated_at' => $now,
+ ])
+ ->all();
+
+ if ($rows !== []) {
+ FormSubmissionFile::query()->insertOrIgnore($rows);
+ }
+ }
+}
diff --git a/api/app/Service/Forms/SubmissionRetentionService.php b/api/app/Service/Forms/SubmissionRetentionService.php
new file mode 100644
index 000000000..50cc57566
--- /dev/null
+++ b/api/app/Service/Forms/SubmissionRetentionService.php
@@ -0,0 +1,64 @@
+<?php
+
+namespace App\Service\Forms;
+
+use App\Models\Forms\Form;
+use App\Models\Forms\FormSubmission;
+use Carbon\CarbonImmutable;
+use Carbon\CarbonInterface;
+
+class SubmissionRetentionService
+{
+ public function __construct(private DeleteFormSubmission $deleteSubmission)
+ {
+ }
+
+ public function cutoff(Form $form, ?CarbonInterface $reference = null): ?CarbonImmutable
+ {
+ $value = $form->submission_retention_value;
+ $unit = $form->submission_retention_unit;
+
+ if (!$value || !in_array($unit, Form::SUBMISSION_RETENTION_UNITS, true)) {
+ return null;
+ }
+
+ $reference = CarbonImmutable::instance($reference ?? now());
+
+ return match ($unit) {
+ 'day' => $reference->subDays($value),
+ 'week' => $reference->subWeeks($value),
+ 'month' => $reference->subMonthsNoOverflow($value),
+ 'year' => $reference->subYearsNoOverflow($value),
+ };
+ }
+
+ public function countExpired(Form $form, ?CarbonInterface $reference = null): int
+ {
+ $cutoff = $this->cutoff($form, $reference);
+
+ if (!$cutoff) {
+ return 0;
+ }
+
+ return $form->submissions()
+ ->where('updated_at', '<=', $cutoff)
+ ->count();
+ }
+
+ public function purge(Form $form, ?CarbonInterface $reference = null): int
+ {
+ $cutoff = $this->cutoff($form, $reference);
+
+ if (!$cutoff) {
+ return 0;
+ }
+
+ $submissionIds = $form->submissions()
+ ->where('updated_at', '<=', $cutoff)
+ ->select('id')
+ ->lazyById(100)
+ ->map(fn (FormSubmission $submission) => $submission->id);
+
+ return $this->deleteSubmission->executeMany($form, $submissionIds, $cutoff);
+ }
+}
diff --git a/api/database/migrations/2026_07_20_000000_add_submission_retention_to_forms_table.php b/api/database/migrations/2026_07_20_000000_add_submission_retention_to_forms_table.php
new file mode 100644
index 000000000..6a5e3b03b
--- /dev/null
+++ b/api/database/migrations/2026_07_20_000000_add_submission_retention_to_forms_table.php
@@ -0,0 +1,33 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class () extends Migration {
+ public function up(): void
+ {
+ Schema::table('forms', function (Blueprint $table) {
+ $table->unsignedSmallInteger('submission_retention_value')->nullable();
+ $table->string('submission_retention_unit', 10)->nullable();
+ });
+
+ Schema::table('form_submissions', function (Blueprint $table) {
+ $table->index(['form_id', 'updated_at'], 'form_submissions_form_id_updated_at_index');
+ });
+ }
+
+ public function down(): void
+ {
+ Schema::table('form_submissions', function (Blueprint $table) {
+ $table->dropIndex('form_submissions_form_id_updated_at_index');
+ });
+
+ Schema::table('forms', function (Blueprint $table) {
+ $table->dropColumn([
+ 'submission_retention_value',
+ 'submission_retention_unit',
+ ]);
+ });
+ }
+};
diff --git a/api/database/migrations/2026_07_20_000001_create_form_submission_file_deletions_table.php b/api/database/migrations/2026_07_20_000001_create_form_submission_file_deletions_table.php
new file mode 100644
index 000000000..52810c577
--- /dev/null
+++ b/api/database/migrations/2026_07_20_000001_create_form_submission_file_deletions_table.php
@@ -0,0 +1,26 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class () extends Migration {
+ public function up(): void
+ {
+ Schema::create('form_submission_file_deletions', function (Blueprint $table) {
+ $table->id();
+ $table->text('path');
+ $table->unsignedInteger('attempts')->default(0);
+ $table->text('last_error')->nullable();
+ $table->timestamp('next_attempt_at')->useCurrent();
+ $table->timestamps();
+
+ $table->index(['next_attempt_at', 'id']);
+ });
+ }
+
+ public function down(): void
+ {
+ Schema::dropIfExists('form_submission_file_deletions');
+ }
+};
diff --git a/api/database/migrations/2026_07_20_000002_create_form_submission_files_table.php b/api/database/migrations/2026_07_20_000002_create_form_submission_files_table.php
new file mode 100644
index 000000000..3965d27d3
--- /dev/null
+++ b/api/database/migrations/2026_07_20_000002_create_form_submission_files_table.php
@@ -0,0 +1,27 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class () extends Migration {
+ public function up(): void
+ {
+ Schema::create('form_submission_files', function (Blueprint $table) {
+ $table->id();
+ $table->foreignId('form_submission_id')
+ ->constrained('form_submissions')
+ ->cascadeOnDelete();
+ $table->text('path');
+ $table->char('path_hash', 64);
+ $table->timestamps();
+
+ $table->unique(['form_submission_id', 'path_hash']);
+ });
+ }
+
+ public function down(): void
+ {
+ Schema::dropIfExists('form_submission_files');
+ }
+};
diff --git a/api/tests/Feature/Submissions/SubmissionRetentionTest.php b/api/tests/Feature/Submissions/SubmissionRetentionTest.php
new file mode 100644
index 000000000..2eeed5c06
--- /dev/null
+++ b/api/tests/Feature/Submissions/SubmissionRetentionTest.php
@@ -0,0 +1,628 @@
+<?php
+
+use App\Http\Resources\FormResource;
+use App\Jobs\Form\DeletePendingSubmissionFile;
+use App\Jobs\Form\PurgeExpiredFormSubmissions as PurgeExpiredFormSubmissionsJob;
+use App\Models\Forms\Form;
+use App\Models\Forms\FormSubmission;
+use App\Models\Forms\FormSubmissionFile;
+use App\Models\Forms\FormSubmissionFileDeletion;
+use App\Models\Version;
+use App\Service\Forms\DeleteFormSubmission;
+use App\Service\Forms\FormSummaryService;
+use App\Service\Forms\SubmissionRetentionService;
+use App\Service\Storage\FileUploadPathService;
+use Carbon\Carbon;
+use Carbon\CarbonImmutable;
+use Illuminate\Support\Facades\Artisan;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Queue;
+use Illuminate\Support\Facades\Storage;
+
+afterEach(function () {
+ Carbon::setTestNow();
+});
+
+function createRetentionForm($test, array $attributes = [])
+{
+ $user = $test->actingAsUser();
+ $workspace = $test->createUserWorkspace($user);
+
+ return $test->createForm($user, $workspace, array_merge([
+ 'submission_retention_value' => 3,
+ 'submission_retention_unit' => 'day',
+ ], $attributes));
+}
+
+function createRetentionSubmission($form, CarbonImmutable $updatedAt, array $data = [])
+{
+ $submission = $form->submissions()->create([
+ 'data' => $data,
+ 'status' => FormSubmission::STATUS_COMPLETED,
+ ]);
+
+ $submission->timestamps = false;
+ $submission->updated_at = $updatedAt;
+ $submission->saveQuietly();
+ $submission->timestamps = true;
+
+ return $submission;
+}
+
+it('stores a custom submission retention period through the form API', function () {
+ $form = createRetentionForm($this, [
+ 'submission_retention_value' => null,
+ 'submission_retention_unit' => null,
+ ]);
+ $formData = (new FormResource($form))->toArray(request());
+ $formData['submission_retention_value'] = 17;
+ $formData['submission_retention_unit'] = 'day';
+
+ $this->putJson(route('open.forms.update', $form), $formData)
+ ->assertSuccessful()
+ ->assertJsonPath('form.submission_retention_value', 17)
+ ->assertJsonPath('form.submission_retention_unit', 'day');
+
+ expect($form->fresh())
+ ->submission_retention_value->toBe(17)
+ ->submission_retention_unit->toBe('day');
+});
+
+it('disables retention through the form API by clearing both fields', function () {
+ $form = createRetentionForm($this);
+ $formData = (new FormResource($form))->toArray(request());
+ $formData['submission_retention_value'] = null;
+ $formData['submission_retention_unit'] = null;
+
+ $this->putJson(route('open.forms.update', $form), $formData)
+ ->assertSuccessful()
+ ->assertJsonPath('form.submission_retention_value', null)
+ ->assertJsonPath('form.submission_retention_unit', null);
+
+ $form->refresh();
+ expect($form)
+ ->submission_retention_value->toBeNull()
+ ->submission_retention_unit->toBeNull();
+});
+
+it('requires a complete and valid retention value and unit pair', function (array $overrides, string $invalidField) {
+ $form = createRetentionForm($this, [
+ 'submission_retention_value' => null,
+ 'submission_retention_unit' => null,
+ ]);
+ $formData = array_merge((new FormResource($form))->toArray(request()), $overrides);
+
+ $this->putJson(route('open.forms.update', $form), $formData)
+ ->assertUnprocessable()
+ ->assertJsonValidationErrors($invalidField);
+})->with([
+ 'unit without value' => [
+ ['submission_retention_value' => null, 'submission_retention_unit' => 'day'],
+ 'submission_retention_value',
+ ],
+ 'value without unit' => [
+ ['submission_retention_value' => 3, 'submission_retention_unit' => null],
+ 'submission_retention_unit',
+ ],
+ 'unsupported unit' => [
+ ['submission_retention_value' => 3, 'submission_retention_unit' => 'hour'],
+ 'submission_retention_unit',
+ ],
+ 'zero value' => [
+ ['submission_retention_value' => 0, 'submission_retention_unit' => 'day'],
+ 'submission_retention_value',
+ ],
+ 'value above maximum' => [
+ ['submission_retention_value' => 3651, 'submission_retention_unit' => 'day'],
+ 'submission_retention_value',
+ ],
+]);
+
+it('does not expose retention settings on public forms', function () {
+ $form = createRetentionForm($this);
+
+ $this->actingAsGuest();
+
+ $resource = (new FormResource($form->fresh()))->toArray(request());
+
+ expect($resource)
+ ->not->toHaveKey('submission_retention_value')
+ ->not->toHaveKey('submission_retention_unit');
+});
+
+it('calculates calendar-aware retention cutoffs for every supported unit', function (
+ int $value,
+ string $unit,
+ string $expected
+) {
+ $form = createRetentionForm($this, [
+ 'submission_retention_value' => $value,
+ 'submission_retention_unit' => $unit,
+ ]);
+ $reference = CarbonImmutable::parse('2024-03-31 12:00:00');
+
+ $cutoff = app(SubmissionRetentionService::class)->cutoff($form, $reference);
+
+ expect($cutoff->toDateTimeString())->toBe($expected);
+})->with([
+ 'days' => [3, 'day', '2024-03-28 12:00:00'],
+ 'weeks' => [2, 'week', '2024-03-17 12:00:00'],
+ 'months without overflow' => [1, 'month', '2024-02-29 12:00:00'],
+ 'years without overflow' => [1, 'year', '2023-03-31 12:00:00'],
+]);
+
+it('purges expired submissions based on their last update and keeps newer submissions', function () {
+ $now = CarbonImmutable::parse('2026-07-20 12:00:00');
+ Carbon::setTestNow($now);
+ $form = createRetentionForm($this);
+ $expired = createRetentionSubmission($form, $now->subDays(4));
+ $boundary = createRetentionSubmission($form, $now->subDays(3));
+ $recent = createRetentionSubmission($form, $now->subDays(2));
+
+ $deleted = app(SubmissionRetentionService::class)->purge($form, $now);
+
+ expect($deleted)->toBe(2);
+ $this->assertDatabaseMissing('form_submissions', ['id' => $expired->id]);
+ $this->assertDatabaseMissing('form_submissions', ['id' => $boundary->id]);
+ $this->assertDatabaseHas('form_submissions', ['id' => $recent->id]);
+});
+
+it('revalidates the last update while holding the deletion lock', function () {
+ $now = CarbonImmutable::parse('2026-07-20 12:00:00');
+ $form = createRetentionForm($this);
+ $submission = createRetentionSubmission($form, $now->subDays(4));
+
+ $submission->timestamps = false;
+ $submission->updated_at = $now->subMinute();
+ $submission->saveQuietly();
+ $submission->timestamps = true;
+
+ $deleted = app(DeleteFormSubmission::class)->execute(
+ $form,
+ $submission->id,
+ $now->subDays(3)
+ );
+
+ expect($deleted)->toBeFalse();
+ $this->assertDatabaseHas('form_submissions', ['id' => $submission->id]);
+});
+
+it('never deletes a submission belonging to another form', function () {
+ $form = createRetentionForm($this);
+ $otherForm = $this->createForm(auth()->user(), $form->workspace);
+ $submission = createRetentionSubmission(
+ $otherForm,
+ CarbonImmutable::parse('2026-07-01 12:00:00')
+ );
+
+ $deleted = app(DeleteFormSubmission::class)->execute($form, $submission->id);
+
+ expect($deleted)->toBeFalse();
+ $this->assertDatabaseHas('form_submissions', [
+ 'id' => $submission->id,
+ 'form_id' => $otherForm->id,
+ ]);
+});
+
+it('keeps an old partial submission that was updated within the retention period', function () {
+ $now = CarbonImmutable::parse('2026-07-20 12:00:00');
+ Carbon::setTestNow($now);
+ $form = createRetentionForm($this);
+ $submission = createRetentionSubmission($form, $now->subDay());
+
+ $submission->timestamps = false;
+ $submission->created_at = $now->subDays(10);
+ $submission->status = FormSubmission::STATUS_PARTIAL;
+ $submission->saveQuietly();
+ $submission->timestamps = true;
+
+ expect(app(SubmissionRetentionService::class)->purge($form, $now))->toBe(0);
+ $this->assertDatabaseHas('form_submissions', ['id' => $submission->id]);
+});
+
+it('does not purge submissions when retention is disabled', function () {
+ $now = CarbonImmutable::parse('2026-07-20 12:00:00');
+ $form = createRetentionForm($this, [
+ 'submission_retention_value' => null,
+ 'submission_retention_unit' => null,
+ ]);
+ $submission = createRetentionSubmission($form, $now->subYear());
+
+ expect(app(SubmissionRetentionService::class)->purge($form, $now))->toBe(0);
+ $this->assertDatabaseHas('form_submissions', ['id' => $submission->id]);
+});
+
+it('fails closed when persisted retention settings are invalid', function () {
+ $now = CarbonImmutable::parse('2026-07-20 12:00:00');
+ $form = createRetentionForm($this);
+ $form->forceFill(['submission_retention_unit' => 'hour'])->saveQuietly();
+ $submission = createRetentionSubmission($form, $now->subYear());
+
+ expect(app(SubmissionRetentionService::class)->purge($form, $now))->toBe(0);
+ $this->assertDatabaseHas('form_submissions', ['id' => $submission->id]);
+});
+
+it('permanently deletes uploaded files and submission versions', function () {
+ Queue::fake();
+
+ Storage::fake();
+ $now = CarbonImmutable::parse('2026-07-20 12:00:00');
+ Carbon::setTestNow($now);
+ $form = createRetentionForm($this);
+ $fileFieldId = collect($form->properties)->firstWhere('type', 'files')['id'];
+ $fileName = 'expired-document.pdf';
+ $filePath = FileUploadPathService::getFileUploadPath($form->id, $fileName);
+ Storage::put($filePath, 'expired contents');
+
+ $submission = createRetentionSubmission($form, $now->subDays(4), [
+ $fileFieldId => [$fileName],
+ ]);
+ $submission->update(['data' => [$fileFieldId => [$fileName], 'edited' => true]]);
+ $submission->timestamps = false;
+ $submission->updated_at = $now->subDays(4);
+ $submission->saveQuietly();
+ $submission->timestamps = true;
+
+ expect($submission->versions()->count())->toBeGreaterThan(0);
+
+ app(SubmissionRetentionService::class)->purge($form, $now);
+
+ $deletion = FormSubmissionFileDeletion::where('path', $filePath)->firstOrFail();
+ (new DeletePendingSubmissionFile($deletion->id))->handle();
+
+ Storage::assertMissing($filePath);
+ $this->assertDatabaseMissing('form_submission_file_deletions', ['id' => $deletion->id]);
+ $this->assertDatabaseMissing('form_submissions', ['id' => $submission->id]);
+ expect(Version::query()
+ ->where('versionable_type', FormSubmission::class)
+ ->where('versionable_id', (string) $submission->id)
+ ->count())->toBe(0);
+});
+
+it('deletes replaced files after their submission versions have rotated out', function () {
+ Queue::fake();
+ Storage::fake();
+
+ $now = CarbonImmutable::parse('2026-07-20 12:00:00');
+ $form = createRetentionForm($this);
+ $fileFieldId = collect($form->properties)->firstWhere('type', 'files')['id'];
+ $oldFileName = 'previous-document.pdf';
+ $currentFileName = 'current-document.pdf';
+ $oldFilePath = FileUploadPathService::getFileUploadPath($form->id, $oldFileName);
+ $currentFilePath = FileUploadPathService::getFileUploadPath($form->id, $currentFileName);
+ Storage::put($oldFilePath, 'previous contents');
+ Storage::put($currentFilePath, 'current contents');
+
+ $submission = createRetentionSubmission($form, $now->subDays(4), [
+ $fileFieldId => [$oldFileName],
+ ]);
+ $submission->update(['data' => [$fileFieldId => [$currentFileName]]]);
+
+ foreach (range(1, 6) as $revision) {
+ $submission->update(['data' => [
+ $fileFieldId => [$currentFileName],
+ 'revision' => $revision,
+ ]]);
+ }
+
+ expect($submission->versions()->get()->contains(function (Version $version) use ($fileFieldId, $oldFileName) {
+ return $version->getModel()->data[$fileFieldId] === [$oldFileName];
+ }))->toBeFalse();
+ expect(FormSubmissionFile::query()
+ ->where('form_submission_id', $submission->id)
+ ->whereIn('path', [$oldFilePath, $currentFilePath])
+ ->count())->toBe(2);
+
+ app(DeleteFormSubmission::class)->execute($form, $submission->id);
+
+ $deletions = FormSubmissionFileDeletion::query()
+ ->whereIn('path', [$oldFilePath, $currentFilePath])
+ ->get();
+
+ expect($deletions)->toHaveCount(2);
+
+ $deletions->each(
+ fn (FormSubmissionFileDeletion $deletion) =>
+ (new DeletePendingSubmissionFile($deletion->id))->handle()
+ );
+
+ Storage::assertMissing($oldFilePath);
+ Storage::assertMissing($currentFilePath);
+ $this->assertDatabaseMissing('form_submission_files', ['form_submission_id' => $submission->id]);
+ $this->assertDatabaseMissing('form_submission_file_deletions', ['path' => $oldFilePath]);
+ $this->assertDatabaseMissing('form_submission_file_deletions', ['path' => $currentFilePath]);
+});
+
+it('tracks the original file when a legacy submission is updated for the first time', function () {
+ Queue::fake();
+ Storage::fake();
+
+ $form = createRetentionForm($this);
+ $fileFieldId = collect($form->properties)->firstWhere('type', 'files')['id'];
+ $oldFileName = 'legacy-document.pdf';
+ $newFileName = 'replacement-document.pdf';
+ $oldFilePath = FileUploadPathService::getFileUploadPath($form->id, $oldFileName);
+ $newFilePath = FileUploadPathService::getFileUploadPath($form->id, $newFileName);
+ Storage::put($oldFilePath, 'legacy contents');
+ Storage::put($newFilePath, 'replacement contents');
+
+ $submission = FormSubmission::withoutEvents(fn () => $form->submissions()->create([
+ 'data' => [$fileFieldId => [$oldFileName]],
+ 'status' => FormSubmission::STATUS_COMPLETED,
+ ]));
+
+ expect($submission->storedFiles()->count())->toBe(0);
+
+ $submission->update(['data' => [$fileFieldId => [$newFileName]]]);
+
+ expect($submission->storedFiles()
+ ->whereIn('path', [$oldFilePath, $newFilePath])
+ ->count())->toBe(2);
+
+ app(DeleteFormSubmission::class)->execute($form, $submission->id);
+
+ FormSubmissionFileDeletion::query()
+ ->whereIn('path', [$oldFilePath, $newFilePath])
+ ->get()
+ ->each(
+ fn (FormSubmissionFileDeletion $deletion) =>
+ (new DeletePendingSubmissionFile($deletion->id))->handle()
+ );
+
+ Storage::assertMissing($oldFilePath);
+ Storage::assertMissing($newFilePath);
+});
+
+it('keeps a retryable outbox entry when an uploaded file cannot be deleted', function () {
+ Queue::fake();
+
+ Storage::fake();
+ $now = CarbonImmutable::parse('2026-07-20 12:00:00');
+ $form = createRetentionForm($this);
+ $fileFieldId = collect($form->properties)->firstWhere('type', 'files')['id'];
+ $fileName = 'undeletable-document.pdf';
+ $filePath = FileUploadPathService::getFileUploadPath($form->id, $fileName);
+ $submission = createRetentionSubmission($form, $now->subDays(4), [
+ $fileFieldId => [$fileName],
+ ]);
+ $submission->update(['data' => [$fileFieldId => [$fileName], 'edited' => true]]);
+
+ app(DeleteFormSubmission::class)->execute($form, $submission->id);
+ $deletion = FormSubmissionFileDeletion::where('path', $filePath)->firstOrFail();
+
+ Storage::shouldReceive('exists')
+ ->once()
+ ->with($filePath)
+ ->andReturnTrue();
+ Storage::shouldReceive('delete')
+ ->once()
+ ->with($filePath)
+ ->andReturnFalse();
+
+ expect(fn () => (new DeletePendingSubmissionFile($deletion->id))->handle())
+ ->toThrow(\RuntimeException::class, 'Unable to delete submission file');
+
+ $this->assertDatabaseMissing('form_submissions', ['id' => $submission->id]);
+ $this->assertDatabaseHas('form_submission_file_deletions', [
+ 'id' => $deletion->id,
+ 'attempts' => 1,
+ ]);
+});
+
+it('keeps the submission and file when the surrounding database transaction rolls back', function () {
+ Queue::fake();
+ Storage::fake();
+
+ $now = CarbonImmutable::parse('2026-07-20 12:00:00');
+ $form = createRetentionForm($this);
+ $fileFieldId = collect($form->properties)->firstWhere('type', 'files')['id'];
+ $fileName = 'rollback-document.pdf';
+ $filePath = FileUploadPathService::getFileUploadPath($form->id, $fileName);
+ Storage::put($filePath, 'must remain stored');
+ $submission = createRetentionSubmission($form, $now->subDays(4), [
+ $fileFieldId => [$fileName],
+ ]);
+
+ expect(fn () => DB::transaction(function () use ($form, $submission) {
+ app(DeleteFormSubmission::class)->execute($form, $submission->id);
+
+ throw new RuntimeException('Abort surrounding operation');
+ }))->toThrow(RuntimeException::class, 'Abort surrounding operation');
+
+ $this->assertDatabaseHas('form_submissions', ['id' => $submission->id]);
+ $this->assertDatabaseHas('form_submission_files', [
+ 'form_submission_id' => $submission->id,
+ 'path' => $filePath,
+ ]);
+ $this->assertDatabaseMissing('form_submission_file_deletions', ['path' => $filePath]);
+ Storage::assertExists($filePath);
+ Queue::assertNotPushed(DeletePendingSubmissionFile::class);
+});
+
+it('deletes files referenced by removed form properties', function () {
+ Queue::fake();
+
+ Storage::fake();
+ $now = CarbonImmutable::parse('2026-07-20 12:00:00');
+ $form = createRetentionForm($this);
+ $fileProperty = collect($form->properties)->firstWhere('type', 'files');
+ $fileName = 'removed-field-document.pdf';
+ $filePath = FileUploadPathService::getFileUploadPath($form->id, $fileName);
+ Storage::put($filePath, 'expired contents');
+ $form->forceFill([
+ 'properties' => collect($form->properties)
+ ->reject(fn ($property) => $property['id'] === $fileProperty['id'])
+ ->values()
+ ->all(),
+ 'removed_properties' => array_merge($form->removed_properties, [$fileProperty]),
+ ])->saveQuietly();
+ $submission = createRetentionSubmission($form, $now->subDays(4), [
+ $fileProperty['id'] => [$fileName],
+ ]);
+
+ app(DeleteFormSubmission::class)->execute($form, $submission->id);
+ $deletion = FormSubmissionFileDeletion::where('path', $filePath)->firstOrFail();
+ (new DeletePendingSubmissionFile($deletion->id))->handle();
+
+ Storage::assertMissing($filePath);
+ $this->assertDatabaseMissing('form_submission_file_deletions', ['id' => $deletion->id]);
+});
+
+it('does not fail a committed deletion when cache invalidation fails', function () {
+ $now = CarbonImmutable::parse('2026-07-20 12:00:00');
+ $form = createRetentionForm($this);
+ $submission = createRetentionSubmission($form, $now->subDays(4));
+ $summaryService = Mockery::mock(FormSummaryService::class);
+ $summaryService->shouldReceive('clearFormSummaryCache')
+ ->once()
+ ->andThrow(new \RuntimeException('Cache unavailable'));
+ $deleteSubmission = new DeleteFormSubmission($summaryService);
+
+ $deleted = $deleteSubmission->execute($form, $submission->id);
+
+ expect($deleted)->toBeTrue();
+ $this->assertDatabaseMissing('form_submissions', ['id' => $submission->id]);
+});
+
+it('processes more submissions than one deletion batch', function () {
+ $now = CarbonImmutable::parse('2026-07-20 12:00:00');
+ $form = createRetentionForm($this);
+
+ foreach (range(1, 105) as $index) {
+ createRetentionSubmission($form, $now->subDays(4), ['index' => $index]);
+ }
+
+ $summaryService = Mockery::mock(FormSummaryService::class);
+ $summaryService->shouldReceive('clearFormSummaryCache')
+ ->once()
+ ->with(Mockery::on(fn (Form $cachedForm) => $cachedForm->is($form)));
+ $retentionService = new SubmissionRetentionService(
+ new DeleteFormSubmission($summaryService)
+ );
+
+ expect($retentionService->purge($form, $now))->toBe(105);
+ expect($form->submissions()->count())->toBe(0);
+});
+
+it('supports a dry run without deleting expired submissions', function () {
+ $now = CarbonImmutable::parse('2026-07-20 12:00:00');
+ Carbon::setTestNow($now);
+ $form = createRetentionForm($this);
+ $submission = createRetentionSubmission($form, $now->subDays(4));
+
+ $exitCode = Artisan::call('forms:purge-expired-submissions', [
+ '--form' => $form->id,
+ '--dry-run' => true,
+ ]);
+
+ expect($exitCode)->toBe(0);
+ expect(Artisan::output())->toContain('1 submission(s) would be deleted');
+ $this->assertDatabaseHas('form_submissions', ['id' => $submission->id]);
+});
+
+it('dispatches a purge job for a soft-deleted form', function () {
+ Queue::fake();
+ $now = CarbonImmutable::parse('2026-07-20 12:00:00');
+ Carbon::setTestNow($now);
+ $form = createRetentionForm($this);
+ $submission = createRetentionSubmission($form, $now->subDays(4));
+ $form->delete();
+
+ Artisan::call('forms:purge-expired-submissions', ['--form' => $form->id]);
+
+ Queue::assertPushed(
+ PurgeExpiredFormSubmissionsJob::class,
+ fn (PurgeExpiredFormSubmissionsJob $job) => $job->formId === $form->id
+ );
+
+ (new PurgeExpiredFormSubmissionsJob($form->id))
+ ->handle(app(SubmissionRetentionService::class));
+
+ $this->assertDatabaseMissing('form_submissions', ['id' => $submission->id]);
+});
+
+it('dispatches independent purge jobs for every configured form', function () {
+ Queue::fake();
+ $firstForm = createRetentionForm($this);
+ $secondForm = $this->createForm(auth()->user(), $firstForm->workspace, [
+ 'submission_retention_value' => 3,
+ 'submission_retention_unit' => 'day',
+ ]);
+
+ $exitCode = Artisan::call('forms:purge-expired-submissions');
+
+ expect($exitCode)->toBe(0);
+ Queue::assertPushed(PurgeExpiredFormSubmissionsJob::class, 2);
+ Queue::assertPushed(
+ PurgeExpiredFormSubmissionsJob::class,
+ fn (PurgeExpiredFormSubmissionsJob $job) => in_array($job->formId, [
+ $firstForm->id,
+ $secondForm->id,
+ ], true)
+ );
+});
+
+it('reloads the form policy once when a purge job starts', function () {
+ $now = CarbonImmutable::parse('2026-07-20 12:00:00');
+ Carbon::setTestNow($now);
+ $form = createRetentionForm($this);
+ $submission = createRetentionSubmission($form, $now->subDays(4));
+ $job = new PurgeExpiredFormSubmissionsJob($form->id);
+ $form->forceFill([
+ 'submission_retention_value' => null,
+ 'submission_retention_unit' => null,
+ ])->saveQuietly();
+
+ $job->handle(app(SubmissionRetentionService::class));
+
+ $this->assertDatabaseHas('form_submissions', ['id' => $submission->id]);
+});
+
+it('redispatches stale pending file deletions', function () {
+ Queue::fake();
+ $deletion = FormSubmissionFileDeletion::create([
+ 'path' => 'forms/1/submissions/stale.pdf',
+ 'next_attempt_at' => now()->subHour(),
+ ]);
+
+ $exitCode = Artisan::call('forms:retry-pending-submission-file-deletions');
+ $firstOutput = Artisan::output();
+ $secondExitCode = Artisan::call('forms:retry-pending-submission-file-deletions');
+ $secondOutput = Artisan::output();
+
+ expect($exitCode)->toBe(0);
+ expect($secondExitCode)->toBe(0);
+ expect($firstOutput)->toContain('Claimed 1 pending file deletion(s)');
+ expect($secondOutput)->toContain('Claimed 0 pending file deletion(s)');
+ Queue::assertPushed(DeletePendingSubmissionFile::class, 1);
+ Queue::assertPushed(
+ DeletePendingSubmissionFile::class,
+ fn (DeletePendingSubmissionFile $job) =>
+ $job->deletionId === $deletion->id
+ );
+});
+
+it('rotates retry claims so older pending jobs cannot starve newer ones', function () {
+ Queue::fake();
+ $firstDeletion = FormSubmissionFileDeletion::create([
+ 'path' => 'forms/1/submissions/first-stale.pdf',
+ 'next_attempt_at' => now()->subHours(2),
+ ]);
+ $secondDeletion = FormSubmissionFileDeletion::create([
+ 'path' => 'forms/1/submissions/second-stale.pdf',
+ 'next_attempt_at' => now()->subHour(),
+ ]);
+
+ Artisan::call('forms:retry-pending-submission-file-deletions', ['--limit' => 1]);
+ Artisan::call('forms:retry-pending-submission-file-deletions', ['--limit' => 1]);
+
+ Queue::assertPushed(DeletePendingSubmissionFile::class, 2);
+ Queue::assertPushed(
+ DeletePendingSubmissionFile::class,
+ fn (DeletePendingSubmissionFile $job) => $job->deletionId === $firstDeletion->id
+ );
+ Queue::assertPushed(
+ DeletePendingSubmissionFile::class,
+ fn (DeletePendingSubmissionFile $job) => $job->deletionId === $secondDeletion->id
+ );
+});
diff --git a/api/tests/Feature/Submissions/SubmissionTest.php b/api/tests/Feature/Submissions/SubmissionTest.php
index 2cc3e6cd4..bccc7e589 100644
--- a/api/tests/Feature/Submissions/SubmissionTest.php
+++ b/api/tests/Feature/Submissions/SubmissionTest.php
@@ -1,5 +1,7 @@
<?php
+use App\Models\Version;
+
it('can delete form submission', function () {
$user = $this->actingAsUser();
$workspace = $this->createUserWorkspace($user);
@@ -12,6 +14,10 @@ it('can delete form submission', function () {
'message' => 'Form submission saved.',
]);
$submission = $form->submissions()->first();
+ $submission->update(['data' => array_merge($submission->data, ['edited' => true])]);
+ $versionIds = $submission->versions()->pluck('version_id');
+ expect($versionIds)->not->toBeEmpty();
+
$this->deleteJson(route('open.forms.submissions.destroy', ['form' => $form, 'submission_id' => $submission->id]))
->assertSuccessful()
->assertJson([
@@ -19,6 +25,7 @@ it('can delete form submission', function () {
'message' => 'Record successfully removed.',
]);
expect($form->submissions()->count())->toBe(0);
+ expect(Version::query()->whereIn('version_id', $versionIds)->count())->toBe(0);
});
it('can delete multiple form submissions', function () {
diff --git a/client/components/open/forms/components/form-components/FormSubmissionSettings.vue b/client/components/open/forms/components/form-components/FormSubmissionSettings.vue
index 4a4ba06e8..205bdb579 100644
--- a/client/components/open/forms/components/form-components/FormSubmissionSettings.vue
+++ b/client/components/open/forms/components/form-components/FormSubmissionSettings.vue
@@ -117,6 +117,69 @@
</ToggleSwitchInput>
</div>
+ <div class="mb-8 border-t pt-4">
+ <h4 class="font-semibold">
+ Submission Retention
+ </h4>
+ <p class="text-neutral-500 text-sm mb-4">
+ Control how long submitted data remains stored in OpnForm.
+ </p>
+
+ <ToggleSwitchInput
+ v-model="retentionEnabled"
+ name="submission_retention_enabled"
+ label="Automatically delete old submissions"
+ help="Permanently deletes submissions after the selected period, measured from their last update."
+ />
+
+ <div
+ v-if="retentionEnabled"
+ class="mt-4 max-w-lg rounded-lg border border-neutral-200 bg-neutral-50 p-4"
+ >
+ <div class="flex flex-col gap-4 sm:flex-row sm:items-end">
+ <TextInput
+ name="submission_retention_value"
+ :form="form"
+ native-type="number"
+ :min="1"
+ :max="3650"
+ :required="true"
+ label="Delete after"
+ class="w-full sm:max-w-40"
+ />
+ <SelectInput
+ name="submission_retention_unit"
+ :form="form"
+ :options="SUBMISSION_RETENTION_UNITS"
+ :required="true"
+ class="w-full sm:max-w-48"
+ />
+ </div>
+
+ <div class="mt-4 flex flex-wrap gap-2">
+ <UButton
+ v-for="shortcut in SUBMISSION_RETENTION_SHORTCUTS"
+ :key="shortcut.label"
+ :label="shortcut.label"
+ color="neutral"
+ variant="soft"
+ size="xs"
+ type="button"
+ @click="applyRetentionShortcut(shortcut)"
+ />
+ </div>
+
+ <UAlert
+ color="warning"
+ icon="i-heroicons-exclamation-triangle"
+ variant="subtle"
+ title="Permanent deletion"
+ description="Changing to a shorter period can delete existing submissions during the next hourly cleanup. Deleted data and uploaded files cannot be restored."
+ class="mt-4"
+ />
+ </div>
+ </div>
+
<ToggleSwitchInput
class="mt-4"
name="enable_ip_tracking"
@@ -286,6 +349,13 @@
<script setup>
import PlanTag from "~/components/app/PlanTag.vue"
import { usePdfTemplates } from '~/composables/query/forms/usePdfTemplates'
+import {
+ SUBMISSION_RETENTION_SHORTCUTS,
+ SUBMISSION_RETENTION_UNITS,
+ applySubmissionRetentionShortcut,
+ setSubmissionRetentionEnabled,
+ syncSubmissionRetentionEnabled
+} from '~/lib/forms/submissionRetention.js'
const workingFormStore = useWorkingFormStore()
const { content: form } = storeToRefs(workingFormStore)
@@ -335,6 +405,45 @@ const clearEmptyFieldsOnUpdate = computed({
set: (value) => { form.value.clear_empty_fields_on_update = value }
})
+const isRetentionEnabled = ref(Boolean(
+ form.value.submission_retention_value
+ && form.value.submission_retention_unit
+))
+
+const retentionEnabled = computed({
+ get: () => isRetentionEnabled.value,
+ set: (enabled) => {
+ isRetentionEnabled.value = enabled
+ setSubmissionRetentionEnabled(form.value, enabled)
+ }
+})
+
+const applyRetentionShortcut = (shortcut) => {
+ applySubmissionRetentionShortcut(form.value, shortcut)
+}
+
+watch(
+ [
+ () => form.value.submission_retention_value,
+ () => form.value.submission_retention_unit
+ ],
+ ([value, unit]) => {
+ isRetentionEnabled.value = syncSubmissionRetentionEnabled(
+ isRetentionEnabled.value,
+ value,
+ unit
+ )
+ }
+)
+
+watch(() => form.value.id, () => {
+ isRetentionEnabled.value = syncSubmissionRetentionEnabled(
+ false,
+ form.value.submission_retention_value,
+ form.value.submission_retention_unit
+ )
+})
+
watch({
redirect_url: form.value.redirect_url,
database_fields_update: form.value.database_fields_update
diff --git a/client/composables/forms/initForm.js b/client/composables/forms/initForm.js
index fd00ca72d..f2c7fdda4 100644
--- a/client/composables/forms/initForm.js
+++ b/client/composables/forms/initForm.js
@@ -41,6 +41,8 @@ export const initForm = (defaultValue = {}, withDefaultProperties = false) => {
max_submissions_count: null,
max_submissions_reached_text:
"This form has now reached the maximum number of allowed submissions and is now closed.",
+ submission_retention_value: null,
+ submission_retention_unit: null,
editable_submissions_button_text: "Edit submission",
confetti_on_submission: false,
diff --git a/client/lib/forms/submissionRetention.js b/client/lib/forms/submissionRetention.js
new file mode 100644
index 000000000..8dd7135e1
--- /dev/null
+++ b/client/lib/forms/submissionRetention.js
@@ -0,0 +1,39 @@
+export const SUBMISSION_RETENTION_UNITS = [
+ { name: 'Days', value: 'day' },
+ { name: 'Weeks', value: 'week' },
+ { name: 'Months', value: 'month' },
+ { name: 'Years', value: 'year' }
+]
+
+export const SUBMISSION_RETENTION_SHORTCUTS = [
+ { label: '1 week', value: 1, unit: 'week' },
+ { label: '1 month', value: 1, unit: 'month' },
+ { label: '6 months', value: 6, unit: 'month' },
+ { label: '1 year', value: 1, unit: 'year' }
+]
+
+export function setSubmissionRetentionEnabled(form, enabled) {
+ if (enabled) {
+ return
+ }
+
+ form.submission_retention_value = null
+ form.submission_retention_unit = null
+}
+
+export function syncSubmissionRetentionEnabled(currentState, value, unit) {
+ if (value && unit) {
+ return true
+ }
+
+ if (value == null && unit == null) {
+ return false
+ }
+
+ return currentState
+}
+
+export function applySubmissionRetentionShortcut(form, shortcut) {
+ form.submission_retention_value = shortcut.value
+ form.submission_retention_unit = shortcut.unit
+}
diff --git a/client/test/unit/submissionRetention.spec.ts b/client/test/unit/submissionRetention.spec.ts
new file mode 100644
index 000000000..179eb996c
--- /dev/null
+++ b/client/test/unit/submissionRetention.spec.ts
@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest'
+import {
+ SUBMISSION_RETENTION_SHORTCUTS,
+ applySubmissionRetentionShortcut,
+ setSubmissionRetentionEnabled,
+ syncSubmissionRetentionEnabled
+} from '../../lib/forms/submissionRetention.js'
+
+describe('submission retention settings', () => {
+ it('does not choose a destructive period when retention is enabled', () => {
+ const form = {
+ submission_retention_value: null,
+ submission_retention_unit: null
+ }
+
+ setSubmissionRetentionEnabled(form, true)
+
+ expect(form).toMatchObject({
+ submission_retention_value: null,
+ submission_retention_unit: null
+ })
+ })
+
+ it('preserves an existing custom period when enabling retention', () => {
+ const form = {
+ submission_retention_value: 3,
+ submission_retention_unit: 'week'
+ }
+
+ setSubmissionRetentionEnabled(form, true)
+
+ expect(form).toMatchObject({
+ submission_retention_value: 3,
+ submission_retention_unit: 'week'
+ })
+ })
+
+ it('clears both persisted fields when retention is disabled', () => {
+ const form = {
+ submission_retention_value: 6,
+ submission_retention_unit: 'month'
+ }
+
+ setSubmissionRetentionEnabled(form, false)
+
+ expect(form).toMatchObject({
+ submission_retention_value: null,
+ submission_retention_unit: null
+ })
+ })
+
+ it.each(SUBMISSION_RETENTION_SHORTCUTS)(
+ 'applies the $label shortcut',
+ (shortcut) => {
+ const form = {
+ submission_retention_value: null,
+ submission_retention_unit: null
+ }
+
+ applySubmissionRetentionShortcut(form, shortcut)
+
+ expect(form).toMatchObject({
+ submission_retention_value: shortcut.value,
+ submission_retention_unit: shortcut.unit
+ })
+ }
+ )
+
+ it('reflects retention values restored by undo', () => {
+ expect(syncSubmissionRetentionEnabled(false, 3, 'day')).toBe(true)
+ })
+
+ it('reflects retention values cleared by undo', () => {
+ expect(syncSubmissionRetentionEnabled(true, null, null)).toBe(false)
+ })
+
+ it('keeps the panel open while a period is partially entered', () => {
+ expect(syncSubmissionRetentionEnabled(true, null, 'day')).toBe(true)
+ expect(syncSubmissionRetentionEnabled(true, 3, null)).toBe(true)
+ })
+})
diff --git a/docs/api-reference/forms/update-form.mdx b/docs/api-reference/forms/update-form.mdx
index 157f3c52c..8418c7b0e 100644
--- a/docs/api-reference/forms/update-form.mdx
+++ b/docs/api-reference/forms/update-form.mdx
@@ -69,6 +69,23 @@ This ensures you retain all existing form fields and don't accidentally overwrit
**Best Practice Example:** If you only want to change form visibility, fetch the form first, update only the `visibility` field locally, then send the complete form back with all its properties intact.
</Tip>
+### Automatically delete old submissions
+
+Set `submission_retention_value` and `submission_retention_unit` together to permanently delete submissions after a retention period. The period is measured from each submission's last update, and the cleanup runs hourly.
+
+```json
+{
+ "submission_retention_value": 3,
+ "submission_retention_unit": "day"
+}
+```
+
+The unit accepts `day`, `week`, `month`, or `year`. Set both fields to `null` to disable automatic deletion.
+
+<Warning>
+Expired submissions, uploaded files, and submission versions are permanently deleted and cannot be restored. Shortening an existing retention period can make older submissions eligible during the next hourly cleanup.
+</Warning>
+
### Body Example
Example request updating title and visibility (note: all required fields must be included):
diff --git a/docs/api-reference/openapi.yaml b/docs/api-reference/openapi.yaml
index 1c9c890a7..cdd6750b9 100644
--- a/docs/api-reference/openapi.yaml
+++ b/docs/api-reference/openapi.yaml
@@ -1316,6 +1316,17 @@ components:
type: boolean
show_progress_bar:
type: boolean
+ submission_retention_value:
+ type: integer
+ minimum: 1
+ maximum: 3650
+ nullable: true
+ description: Number of retention units before a submission is permanently deleted. Set this and submission_retention_unit to null to disable automatic deletion.
+ submission_retention_unit:
+ type: string
+ enum: [day, week, month, year]
+ nullable: true
+ description: Calendar unit used by submission_retention_value. Both retention fields must be provided together.
# Form closure and limits
closes_at: