Submissions

Understand form submissions, their lifecycle statuses, relationships, validation and how to query and export submission data.

Overview

The FormSubmission model represents a completed or in-progress form submission. Submissions track status, timing, submitter information and metadata. Each submission contains multiple FormFieldSubmission records storing individual field values.

Core Properties

Property	Type	Description
`status`	SubmissionStatus	Current status of the submission
`ip_address`	string\|null	IP address of submitter (privacy configurable)
`user_agent`	string\|null	Browser user agent string
`completion_time_seconds`	int\|null	Time taken to complete the form (in seconds)
`submitted_at`	datetime	When the submission was finalized
`metadata`	array	Additional custom data (UTM params, referrer, etc.)

SubmissionStatus Enum

Submissions use a string-backed enum to track their lifecycle:

Draft Submissions

STARTED status indicates a draft submission. Enable allow_save_draft in form settings to let users save progress.

Creating Submissions

Use the Polyform facade to submit form data with automatic validation:

app/Http/Controllers/SubmissionController.php

Draft Submissions

Save partial progress for multi-step or long forms:

Draft Scopes

Use the drafts() and forSubmitter() scopes to query draft submissions efficiently.

Relationships

form - BelongsTo Form (parent form)
submittable - MorphTo (submitting entity, e.g., User)
fieldSubmissions - HasMany FormFieldSubmission (field values)

Value Bag

Access all field values as a convenient array via the value_bag computed attribute:

The value bag is cached and automatically synced with field submissions. It is ideal for displaying submitted data or passing to webhooks.

Query Scopes

drafts() - Filter submissions with STARTED status
forSubmitter($submittable) - Filter by submittable entity

Submittable Trait

Add the HasPolyformSubmissions trait to models that submit forms:

app/Models/User.php

Field Submissions

Individual field values are stored in FormFieldSubmission records:

Value Encoding

Arrays and objects are JSON-encoded. File fields store file paths. The frontend handles serialization automatically.

Validation

The Polyform::submit() method validates all field values using the appropriate FieldValidator for each field type. Validation respects conditional logic and required flags.

Webhooks

Submissions trigger webhook events automatically:

Webhooks are queued, retried on failure and signed with HMAC for security. Configure retries and signing in config/polyform.php.

Exporting Submissions

Export submission data to multiple formats:

Exports respect field labels, format values appropriately and include metadata columns. CSV and Excel exports are Excel-compatible.

Metadata

Store additional context with submissions:

UTM parameters for tracking campaigns
Referrer URLs for source attribution
Device information (captured from user agent)
Custom application data (flags, tags, notes)

Privacy Considerations

IP address and user agent collection can be disabled in form settings. Always comply with privacy regulations when storing submitter data.

Best Practices

Use withCount('submissions') when loading forms to avoid N+1 queries
Enable draft saving for multi-step forms to improve completion rates
Set appropriate max_submissions and max_submissions_per_user limits
Use scopes for efficient querying of large submission datasets
Leverage webhooks for real-time integrations (CRM, email, Slack)
Export submissions regularly for backup and analysis

Steps Templates