Statamic Form Submission Cleaner Laravel Package

Getting Started

This is a Statamic addon (installable in any Laravel app running Statamic 3/4/5), so start by confirming your Statamic version and installing via Composer:

composer require mitydigital/statamic-form-submission-cleaner
php artisan vendor:publish --tag="statamic-form-submission-cleaner-config"

Read the published config file first — it is the entire public API of this package. Look for the retention/pruning settings and the list of forms it applies to. Everything else (the cleanup command, any scheduled job) reads from that file, so understanding the config shape tells you what the addon can and cannot do.

The first real use case: stop form submissions (and their uploaded assets) accumulating forever in storage/statamic/forms/submissions. You point the config at the forms you care about, set a retention window, then wire the provided command into the scheduler:

// routes/console.php (Laravel 11+) or app/Console/Kernel.php
Schedule::command('statamic:form-submission-cleaner') // verify exact signature
    ->daily()
    ->at('03:00');

Run the command manually once with a short retention (e.g. 1 day) in a local environment to see exactly which submissions get deleted before trusting it in production.

Implementation Patterns

Per-form retention. Rather than one global retention period, configure each form separately. Marketing/contact forms often need 30–90 days for follow-up; newsletter or event signups may only need a week. A single global number inevitably becomes the wrong number for one form.

Schedule the cleanup, don't call it in a controller. The cleaner is a batch operation. Wire it into Schedule and let it run off-peak. If you need to trigger it from the control panel or a custom command, wrap it in Artisan::call() rather than duplicating deletion logic in your own code.

Treat it as a GDPR/data-retention control. If you have a privacy policy stating "we keep enquiries for 12 months", this config is your enforcement mechanism. Document the retention value in the codebase and keep it in sync with the policy. Consider exporting long-retention data to a warehouse before the cleaner runs if you need analytics history.

Pair it with a notification/audit hook if your compliance needs it: log counts of deleted submissions per run (wrap the scheduled command in a small custom command that records the output) so you can prove the process ran.

Upgrading from 1.1.0 to 1.1.1 is a drop-in patch — no config changes, no migration, no new options. The change wraps asset values in Arr::wrap, which only affects submissions where an asset field holds a single file rather than an array. If you had previously worked around single-asset fields by forcing them into arrays at the form level, you can now remove that workaround.

Gotchas and Tips

• Asset deletion is the dangerous part. Deleting a submission record is recoverable-ish (restore from backup); deleting the underlying file from the asset container is not. Verify on staging that the cleaner deletes only assets belonging to that submission, and that it doesn't remove an asset that is referenced elsewhere. Before 1.1.1, submissions with a single asset (rather than an array of assets) were not reliably handled — audit any pre-1.1.1 runs for orphaned files left behind, and clean those up manually.
• Back up before the first production run. php please backup or a database + storage/statamic/forms snapshot. Dry-run first by setting an absurdly short retention on a single low-value form.
• Check how the config identifies forms. If it matches on form handle, renaming a form in the Statamic CP silently makes your retention rule stop applying. Re-audit the config whenever you rename or create forms — a new form added later won't be covered unless it matches an existing rule.
• Timezone matters. A daily 03:00 schedule is evaluated in config/app.php's timezone. If your team reasons in UTC and the server is in local time, submissions may survive up to a day longer than you expect. Not usually a problem, but worth knowing when defending the retention period.
• Queues and long runs. If you have hundreds of thousands of submissions, the cleanup can be slow. If the addon dispatches work to a queue, ensure a worker is running; if it doesn't, consider running it more frequently (hourly with a short lookback) rather than one huge nightly pass.
• Extension point: if you need custom logic (exclude flagged submissions, archive before delete), prefer hooking the scheduled command or extending the command class rather than forking the package — the config surface is intentionally small and forks will drift.
• Debugging "nothing got deleted": check (a) the form handle matches the config, (b) submission dates are what you think they are, (c) the scheduler is actually running (schedule:list, and confirm schedule:run is in cron), and (d) the command output for counts. The addon gives little feedback by default, so run it manually in -v mode.