[6.x] Forms 2: Submission Statuses

[duncanmcclean]

This pull request implements submission statuses, allowing submissions to be marked as incomplete/spam without triggering events or integrations.

It lays the groundwork for partial submissions and improved spam protection, while staying backwards compatible.

Statuses

A submission's status is derived from two boolean keys, stored in the submission's data:

• incomplete — a partial submission that hasn't been finished yet (eg. multi-page form which has been started but not completed)
• spam — a submission flagged by spam protection

These are independent, so a submission could be either, both, or neither.

Submission::status() returns a single value for display purposes (complete, incomplete, or spam), and there are isIncomplete() and isSpam() methods for checking submissions in your own code.

Events

Submission::save() is now status aware. A submission that's incomplete or spam is still persisted, but it does not fire the Creating / Created events to prevent existing third-party integrations from acting on incomplete data. It still fires the Saving / Saved events.

A submission only behaves this way when either of the keys are set, so existing submissions fire the same events in the same order as before. This is intentional, to avoid breaking listeners that currently treat Created as the "a submission happened" signal. We may revisit this in v7 (eg. firing Creating / Created for every submission and recommending that listeners listen to the FormSubmitted event instead).

Completing a submission

A new Submission::complete() method is the single place a submission's side effects are released. It:

1. Clears the incomplete and spam keys
2. Persists the submission (respecting the form's store setting)
3. Dispatches SubmissionCreated exactly once
4. Dispatches SendEmails

It deliberately doesn't dispatch the FormSubmitted event because it's used by addons to cancel submissions (eg. Captcha addons) and not every caller wants it.

A normal frontend submission does, so FormController runs its honeypot and FormSubmitted checks and then calls complete(). The "Mark as Not Spam" action does not, because a human has already decided the submission is legitimate and re-dispatching the event could re-flag it as spam. Leaving the dispatch to the caller lets each one decide.

FormController now calls complete(), so single page submissions behave identically to before, with less duplicated logic.

Control Panel

• The submissions listing has a new Status filter, preselected to "Complete", so incomplete and spam submissions are hidden by default but can be revealed by removing or changing the filter.
• A Status column shows each submission's status, and a status badge is shown on the submission detail page.
• A "Mark as Not Spam" action is available on spam submissions. It clears the key and runs the completion side effects, without re-running the spam gate, since a human has overridden the decision.

Cleaning up incomplete submissions

Incomplete submissions are automatically deleted after a configurable number of days, via a scheduled DeleteIncompleteFormSubmissions job. This is controlled by a new config value:

// config/statamic/forms.php

'delete_incomplete_submissions_after' => 7, // days. Set to null to disable.

[godismyjudge95]

I don't know if this is the place for it, but something we built in forms on 5.x was a payment status system. My reason for mentioning, is that it might be nice if statuses were extendable so you could track payments or workflows via the status without having a form field.

Feel free to nix it; just wanted to bring it up.

[duncanmcclean]

When I was planning this out originally, I did think about payments (and their statuses) but came to the conclusion they'd probably be better separate.

Submission statuses represent the status of a submission. It's either spam, incomplete (eg. a partial submission) or complete.

Whereas with payments, they could be: pending, successful, refunded. All of which don't really line up with a submission status.

For example: a visitor might have completed a form, but their payment hasn't processed yet.