Configuration

Type: array · Default: []

Adds exact external origins permitted for completion redirects, for example ['https://partner.example.com']. Configured Craft site origins and safe relative paths are already allowed. Scheme, host and port must match. See Completion and Redirects.

Type: array · Default: ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content']

Lists URL query parameters to copy from the page where the form first loads to the completion redirect. Parameters already in the destination URL take priority. Set [] to disable forwarding. Only simple values are copied; nested data and security tokens are excluded.

Type: array · Default: []

Lists environment variables that editors may use in reference tokens and $NAME notification settings, for example ['PUBLIC_CONTACT_EMAIL']. Only include variables whose values are safe to display in the intended output. The Variable Picker shows their names, not their values. Visitors cannot read environment variables by submitting $NAME as an answer. See Reference Tokens.

Type: string|null · Default: null

Provides the dedicated key used only for encrypted submission field content. Prefer the FORMIE_ENCRYPTION_KEY environment variable so the key is not committed with project files. Generate and save a key to the project’s configured .env file with php craft formie/encryption/generate-key, or add --stdout when an external deployment or secrets system owns the environment. Keep a recoverable copy and use the same key in every environment that must read copied production submissions. See Content Encryption for setup and environment guidance.

Type: array · Default: []

Provides read-only rescue keys while encrypted submission content is moved to the current key. Prefer FORMIE_ENCRYPTION_PREVIOUS_KEYS, supplied as a comma-separated list or JSON array. Remove old keys only after php craft formie/encryption/reencrypt reports that every readable value uses the current key. See Content Encryption for the rotation sequence.

Type: string · Default: 'Formie'

Sets a custom name for the plugin.

Type: string · Default: 'forms'

Sets the default Formie control panel page when clicking Formie in the main navigation.

Type: bool · Default: true

Enables compatibility shims for older Formie APIs, including supported browser events on rendered forms. The browser inherits this setting automatically; no custom JavaScript setup is required. Purge cached form HTML after changing it.

Type: bool · Default: false

Allows rendered forms to refresh request-specific values when initialised on statically cached pages. Formie also treats this as enabled when Blitz is installed and enabled.

Type: string · Default: self::ALLOWED_SUBMIT_METHODS_BOTH

Restricts which submission methods are available in the form builder: both (default), ajax, or page-reload. Payment integrations that require Ajax still force Ajax when applicable.

validateCustomTemplates

Type: bool · Default: true

Checks that custom form template paths exist before they are saved.

defaultFormTemplate

Type: string · Default: ''

Sets the default form template handle used for new forms.

defaultFormStencil

Type: string · Default: ''

Sets a stencil handle to apply automatically when new forms are created without an explicit stencil.

defaultEmailTemplate

Type: string · Default: ''

Sets the default email template handle used for new email notifications.

formDefaults

Type: array · Default: []

Sets structured defaults applied to new forms and stencils, including default submission status, submission title format, privacy settings, submission method, data retention, file-upload deletion behaviour, and appearance settings. Leave a value empty or null to inherit Formie’s built-in behaviour.

notificationDefaults

Type: array · Default: []

Sets defaults applied when a new email notification is created. Leave a value empty or null to inherit Formie’s built-in behaviour.

integrationDefaults

Type: array · Default: []

Controls default captcha integration states for new forms and stencils. Use captchas[handle] with null to inherit each integration’s global enabled state, or true/false to force enable or disable.

enableUnloadWarning

Type: bool · Default: true

Shows an unload warning when a user changes a front-end form and tries to leave without submitting.

errorAriaLive

Type: string · Default: self::ERROR_ARIA_LIVE_POLITE

Controls how front-end validation and submit errors are announced to screen readers. Use polite (default), assertive, or off for visual-only errors. Live validation while typing always uses polite announcements; submit-time errors use this setting.

enableBackSubmission

Type: bool · Default: true

Submits the current page content when a user clicks the Back button on a multi-page form.

enableMultiPageForms

Type: bool · Default: true

Controls whether forms can contain multiple pages in the form builder. When disabled, authors cannot add pages and forms with more than one page cannot be saved.

ajaxTimeout

Type: int · Default: 10

Sets the timeout in seconds for Ajax requests made by Formie’s front-end JavaScript.

filterIntegrationMapping

Type: bool · Default: true

Filters field-mapping options shown in integrations to fields that are usually suitable for the target setting.

includeDraftElementUsage

Type: bool · Default: false

Includes draft elements when Formie checks where a form is used.

includeRevisionElementUsage

Type: bool · Default: false

Includes revision elements when Formie checks where a form is used.

outputConsoleMessages

Type: bool · Default: true

Controls whether Formie’s front-end JavaScript can output console messages.

disabledFields

Type: array · Default: []

Is an array of field classes that should be disabled and unavailable in the form builder.

defaultLabelPosition

Type: string · Default: AboveInput::class

Sets the default label position for new forms and fields.

defaultInstructionsPosition

Type: string · Default: AboveInput::class

Sets the default instruction position for new forms and fields.

fieldDefaults

Type: array · Default: []

Sets per-field-type defaults applied when new fields are added to a form. Keys are field class names; values are arrays of setting handles and values. Field types opt in via supportedDefaults(). Leave a value empty or null to inherit Formie’s built-in behaviour. For example, set File Upload, Date, Phone, Agree, Email, Number, element field, and other supported field defaults with their field class names as keys. Custom field types can opt in via Field Defaults.

allowPublicVolumes

Type: bool · Default: true

Allows File Upload fields to use public asset volumes, and controls whether “Public URL” is available as an email summary value. Configure in Settings → Field Types and Restrictions.

allowMultiSelectDropdowns

Type: bool · Default: true

Controls whether form editors can enable “Allow Multiple” on Dropdown and element fields using a dropdown display type. When disabled, the setting is hidden in the form builder and existing values are forced off. Configure in Settings → Field Types and Restrictions.

allowPhoneCountrySelector

Type: bool · Default: true

Controls whether form editors can enable the country code selector on Phone Number fields. When disabled, the setting is hidden in the form builder and existing values are forced off. For default-off behaviour on new phone fields without hiding the setting, use Field Defaults (countryEnabled: false). Configure in Settings → Field Types and Restrictions.

allowHiddenFieldTemplates

Type: bool · Default: false on new installs; true after upgrading

Allows form editors to select Template as a Hidden field’s default value source. Configure in Settings → Field Types and Restrictions. When disabled, stored Template fields return an empty value and continue to ignore posted input. Their template source is retained. Choose another source before saving an affected form, or re-enable the capability. Custom Value and references remain available.

allowHtmlFieldTwig

Type: bool · Default: false on new installs; true after upgrading

Allows form editors to enable Allow Twig on HTML fields. Each field must also opt in. When disabled, HTML fields already configured for Twig produce no output, and new fields cannot opt in. Stored content is retained. Existing fields can turn off Allow Twig before saving, or an administrator can restore the capability. Configure in Settings → Field Types and Restrictions.

allowHtmlFieldTemplateIncludes

Type: bool · Default: false on new installs; true after upgrading

Allows sandboxed site-template includes in HTML fields. Requires allowHtmlFieldTwig and the field’s Allow Twig setting. When disabled, includes fail with a Twig sandbox error; ordinary permitted Twig expressions still work. This setting does not enable includes in Hidden fields, PDF filenames or other inline templates. Configure in Settings → Field Types and Restrictions.

requireHtmlPurification

Type: bool · Default: true on new installs; false after upgrading

Always purifies HTML field output, including output from Twig and included templates, and hides the field’s Purify Content control. Existing per-field preferences are retained but cannot bypass this requirement. When false, each field’s Purify Content setting applies; new HTML fields still default to purification enabled. Configure in Settings → Field Types and Restrictions.

enableLargeFieldStorage

Type: bool · Default: false

Stores field content in large-text database columns for projects that expect very large submission payloads.

includeFlatpickrCss

Type: bool · Default: true

Controls whether Formie injects Flatpickr styles for Calendar (Advanced) date fields. Set to false when your project already provides its own Flatpickr stylesheet.

plainTextHtmlSanitizationMode

Type: string · Default: self::PLAIN_TEXT_HTML_SANITIZATION_MODE_PRESERVE

Controls how plain-text input values are handled when HTML is submitted. Use preserve or sanitize.

maxStagedUploadFiles

Type: int · Default: 50

Limits the number of files awaiting completion for one browser/form instance across all its upload fields. Bound files on incomplete submissions and expired files still waiting for physical cleanup count towards the limit. Successfully finalized uploads no longer count. Use a positive value; increase it for forms that legitimately collect many files.

maxStagedUploadBytes

Type: int · Default: 67108864 (64 MiB)

Limits the combined bytes awaiting completion within the same browser/form instance. This applies alongside the file-count limit, Craft's maximum per-file size and each field's own limits. Removing unused files or completing the submission releases the corresponding budget. Expiry alone does not release storage until cleanup succeeds. Staged capabilities expire within 30 days, or the shorter positive maxIncompleteSubmissionAge, even when incomplete-submission retention is unlimited. This is a per-instance budget, not a server-wide storage quota.

maxIncompleteSubmissionAge

Type: int · Default: 30

Sets the maximum age of incomplete submissions in days before they are deleted by scheduled cleanup. Set to 0 to disable automatic deletion.

allowLegacySignatureImageUrls

Type: bool · Default: true

Allows previously sent unsigned Formie 2 and Formie 3 Signature image URLs to continue loading for submissions explicitly marked as legacy during the upgrade. New Formie 4 submissions always use signed, non-expiring, exact-value image URLs. Set this to false when historical email images no longer need to load.

enableCsrfValidationForGuests

Type: bool · Default: true

Enables Craft’s CSRF validation checks for anonymous form submissions.

useQueueForNotifications

Type: bool · Default: true

Sends email notifications through Craft’s queue. This is recommended for production sites so form submissions are not slowed down by email delivery.

useQueueForIntegrations

Type: bool · Default: true

Sends integrations through Craft’s queue. This is recommended for production sites so form submissions are not slowed down by third-party APIs.

allowedPrivateIntegrationHosts

Type: array · Default: []

Allows outbound integration requests to trusted private services, such as a self-hosted CRM. Set this in config/formie.php; values saved through the control panel do not grant private-network access. Entries can be exact hostnames (case-insensitive), individual IPv4 or IPv6 addresses, or CIDR ranges. Wildcards, URLs and port numbers are not supported.

<?php

use craft\helpers\App;

return [
    'allowedPrivateIntegrationHosts' => array_values(array_filter(array_map(
        'trim',
        explode(',', (string)App::env('FORMIE_ALLOWED_PRIVATE_HOSTS')),
    ))),
];

For example, set FORMIE_ALLOWED_PRIVATE_HOSTS=crm.internal.example,10.20.30.40,fd12:3456::/48 in your environment. Prefer an exact host or address over a broad range. This permission applies to all outbound integrations, including Web Request URLs that use submitted field values.

Only private IPv4 networks (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) and IPv6 unique-local addresses (fc00::/7) can be allowed. Loopback, link-local, unspecified, multicast, reserved and IPv4 transition addresses remain blocked, even when listed, as does the AWS service range fd00:ec2::/32. Every DNS answer must be public or explicitly allowed. Requests retain DNS pinning, TLS certificate verification, HTTP/HTTPS on ports 80/443, and disabled redirects and proxies. Public endpoints remain allowed without configuration.

queuePriority

Type: int|null · Default: null

Sets the Craft queue priority for notification and integration jobs.

deliveryEvidenceRetentionDays

Type: int · Default: 30

Retains encrypted diagnostic evidence for completed notification and integration deliveries for this many days. Must be at least 1. Cleanup keeps operation identities and audit decisions to prevent accidental replay. Pending, running, uncertain and retryable failed deliveries retain their evidence for reconciliation. Diagnostic views report omitted evidence explicitly when a size or checkpoint limit is reached. Downloading a support bundle requires acknowledgement that it can contain personal submission data.

redirectUri

Type: string|null · Default: null

Overrides the OAuth redirect URI for integration connections. When omitted, Formie uses an action URL (actions/formie/integrations/callback). Environment variables are supported.

paymentWebhookProxyUrl

Type: string|null · Default: null

Controls the dev-mode proxy used for payment webhook and return URLs (for example Mollie webhooks and redirect status pages). When omitted in dev mode, Formie uses https://proxy.verbb.io?return=.... Set to a custom base URL to use your own tunnel/proxy, or set to an empty string to disable the proxy and use local URLs directly. Ignored when Craft dev mode is off. Environment variables are supported.

setOnlyCurrentPagePayload

Type: bool · Default: false

Limits multi-page form payloads to the current page when processing a page request.

submissionsBehaviour

Type: string|array · Default: 'all'

Controls which submissions are saved. The default is all.

submissionStateRetentionDays

Type: int · Default: 30

Sets how long incomplete submission state can be kept for save-and-resume and front-end submission state.

saveResumeTokenTtlDays

Type: int · Default: 14

Sets how many days a Save & Continue link remains valid. The link also stops working if the incomplete submission is removed by its retention settings.

anonymousFormBootstrapRateLimit

Type: int · Default: 30

Limits anonymous form bootstrap requests within the configured rate window. Set to 0 to disable the limit.

anonymousFormRefreshRateLimit

Type: int · Default: 120

Limits anonymous token-refresh requests within the configured rate window. Set to 0 to disable the limit.

anonymousFormRateWindowSeconds

Type: int · Default: 60

Sets the rate-limit window used by anonymous client bootstrap and token-refresh requests.

sentNotifications

Type: bool · Default: true

Enables Sent Notifications.

maxSentNotificationsAge

Type: int · Default: 30

Sets the number of days to keep sent notifications before they are deleted by scheduled cleanup. Set to 0 to disable automatic deletion.

saveSpam

Type: bool · Default: true

Saves spam submissions to the database.

spamLimit

Type: int · Default: 500

Limits how many saved spam submissions are kept.

spamEmailNotifications

Type: bool · Default: false

Allows submissions marked as spam to still trigger email notifications.

spamBehaviour

Type: string · Default: self::SPAM_BEHAVIOUR_SUCCESS

Controls what the user sees when a spam submission is detected. Use showSuccess or showMessage.

spamKeywords

Type: string · Default: ''

Marks a submission as spam when the submitted content matches the configured keywords.

spamBehaviourMessage

Type: string · Default: ''

Sets the message shown when spamBehaviour is showMessage. HTML and Markdown are supported.

sendEmailAlerts

Type: bool · Default: false

Sends an alert email when an email notification fails to send.

alertEmails

Type: array|null · Default: null

Sets additional email addresses that should receive alert emails. Each entry should be an array with an email key. Environment variables are supported.

alertEmailsUserGroup

Type: string|null · Default: null

Optionally sends alert emails to every user in a Craft user group. Additional alertEmails are still sent when configured. At least one of alertEmails or alertEmailsUserGroup is required when sendEmailAlerts is enabled.

emptyValuePlaceholder

Type: string · Default: 'No response.'

Sets the placeholder used when a field has no submitted value in email output.

pdfPaperSize

Type: string · Default: 'letter'

Sets the paper size for generated PDFs.

pdfPaperOrientation

Type: string · Default: 'portrait'

Sets the paper orientation for generated PDFs.

pdfTrustedRemoteHosts

Type: array · Default: []

Allows generated PDFs to load images and other resources from the listed private or reserved hosts. Public HTTP and HTTPS resources work without configuration. Add only hosts you control and intend PDF templates or rich-text fields to access, using hostnames or IP addresses without a scheme or path.

return [
    'pdfTrustedRemoteHosts' => [
        'assets.internal.example',
    ],
];

themeConfig

Type: array · Default: []

Sets the default theme configuration used when rendering forms and fields.

useCssLayers

Type: bool · Default: false

Outputs Formie’s front-end CSS inside a CSS cascade layer.

captchas

Type: array · Default: []

Legacy upgrade input for CAPTCHA configuration. Manage current providers under Formie → Spam Protection → CAPTCHAs or Spam Filtering Services. Provider settings are stored in the installation’s database; configure them separately on production. See Setting Up Production.

defaultExportFolder

Type: string · Default: '@storage/formie-export'

Sets the default folder used by form export console commands.