Statamic Form Submission Cleaner Laravel Package

Technical Evaluation

Architecture fit. mitydigital/statamic-form-submission-cleaner is a Statamic addon, not a general-purpose Laravel package — it depends on Statamic's form-submission repositories and asset container APIs. It fits the standard Statamic addon pattern: auto-discovered service provider, publishable config, and an Artisan command intended to be registered in the Laravel scheduler. That is the right shape for a retention/TTL job and means no forking of Statamic core or custom control-panel code. The trade-off is that the package is only usable in stacks that already run Statamic; it has no value in a plain Laravel app.

Integration feasibility. Low effort. composer require, publish the config, set a retention window, add one scheduler line. No database migrations, no schema changes, no front-end work. The only real configuration surface is retention period, form handles, and which fields hold assets.

Release 1.1.1 assessment. This is a patch with no new features, no deprecations, and no public API change. It wraps asset values in Arr::wrap so that a single-file upload (scalar/asset object) and a multi-file upload (collection) are handled on the same code path. The practical effect is that submissions containing exactly one uploaded file now get their asset deleted alongside the submission record; previously that path could silently skip the file.

• Severity: correctness bug fix, not a breaking change.
• Blast radius: deletion logic — the highest-consequence code in an addon of this type.
• Compliance relevance: the pre-fix behaviour risks orphaned files in storage after the submission record is purged. For teams using this addon to satisfy a data-retention or erasure commitment, that gap is a reportable defect, not a cosmetic one.
• Upgrade risk: negligible; semver patch, no signature changes.

Technical risk. Overall low, with three caveats worth flagging to stakeholders:

1. The fix only changes the code path taken on the next run — it does not retroactively scan storage. Existing orphaned single-file assets from prior versions will only be removed if they are still reachable via a submission record that has not yet been purged. Anything already orphaned stays orphaned; a one-off reconciliation script may be needed.
2. Deletion is destructive and the README-level guarantees around dry-run, logging, and backup expectations need verification before we schedule it against production.
3. Arr::wrap normalises shape but does not de-duplicate: if the same asset is referenced by multiple submissions or by content outside the form, deletion semantics are undefined from the release notes alone.

Key questions for the maintainer / our own spike:

• Which Statamic and PHP versions are supported (3.x/4.x/5.x, PHP 8.1+)?
• Does the cleaner support a dry-run / preview mode, and does it log what it deletes?
• Does it traverse assets nested inside Grid, Replicator, or Bard fields, or only top-level form fields?
• Does it respect per-container filesystem disks and Statamic's asset meta sidecars (.meta folders), or leave those behind?
• Is deletion soft (Statamic's asset recycle bin) or hard?
• Is there any guard against deleting an asset that is referenced elsewhere?

Integration Approach

Stack fit. Laravel 9–11 + Statamic 4/5, running the standard Laravel scheduler (or a queue worker if we wrap the command). Composer-installed, config-driven, no runtime dependency on our application code. Fits alongside the rest of our Statamic addon set without conflict.

Migration path. composer update mitydigital/statamic-form-submission-cleaner to ^1.1.1. No config changes, no data migration, no downtime. If we are on 1.1.0 or below, this is a drop-in patch.

Compatibility. Semver-safe patch bump; no changes to config keys, command signatures, or published assets. Safe to pin to ^1.1 and let Renovate/Dependabot carry future patches. The one thing to confirm is the Statamic major-version constraint in composer.json — that, not the patch level, is what will actually block an upgrade.

Sequencing.

1. Bump to 1.1.1 in a non-production environment.
2. Run the command against a staging copy of the database/storage; capture the count of submissions and assets deleted.
3. Diff storage before/after to confirm single-file assets are now removed and that no shared assets were touched.
4. If we need to clean historical orphans, run a separate, explicitly scoped reconciliation job — do not rely on this patch to do it.
5. Promote to production with the existing schedule entry unchanged; watch the first two runs.
6. Only after (3) passes should we cite this command in any retention or erasure documentation.

Operational Impact

Maintenance. Small, single-vendor package from a digital agency, with a low commit cadence and a small contributor base. Vendor-continuity risk is real but bounded: the code surface is narrow and the logic is simple enough to fork or reimplement in-house in a day or two if maintenance lapses. Recommend pinning and monitoring rather than treating it as critical infrastructure.

Support. GitHub issues/PRs only; no commercial SLA. Acceptable for a background housekeeping job where a delayed fix is inconvenient rather than customer-facing.

Scaling. The command is I/O- and query-bound: it walks submissions, then resolves and deletes assets one at a time. Runtime grows roughly linearly with the retention backlog, and there is likely an N+1 pattern per submission over its asset field. At our current volume this is a non-issue; if submission volume grows by an order of magnitude, expect the first run after a retention-window change to be long. Mitigations: run off-peak, chunk the date range over several nights, or wrap the command in a queued job with a timeout.

Failure modes.

• Over-deletion — an asset referenced outside the submission gets removed. Highest-severity, lowest-probability; test on staging with real shared assets.
• Under-deletion — the pre-1.1.1 behaviour; partly resolved by this release but historical orphans persist.
• Silent no-op — misconfigured form handles or field names mean the command runs green and deletes nothing. Needs a metric or log assertion, not just an exit code.
• Filesystem/permission errors — deletion fails on a subset of assets while the DB row is already gone, widening the orphan set.
• Irreversible run — no confirmed dry-run means a wrong retention value is unrecoverable without a storage backup.

Ramp-up. Very low. A Laravel developer unfamiliar with the package can read the source and be productive in half a day; most of that time should go on the staging dry-run and storage diff, not on the code. The real onboarding cost is procedural: whoever owns data retention needs to know this command exists and what it deletes, so it appears correctly in our retention documentation.