Updating from Freeform 4.x
Due to the nature of this update we recommend anyone upgrading from Freeform 4.x to do so carefully in a development environment and follow the special instructions below.
Key Changes
The Freeform 5.0 update is a major overhaul to the structure, templating, and form builder organization. There are many breaking changes that will allow us to continue to improve Freeform in the future. Please note all key changes below:
Topic | Freeform 4.x | Freeform 5.x | Required Action |
|---|---|---|---|
| Field ManagementAffects: All | Fields were global across all forms, making reusing them easier (though had its many downfalls) | Fields are created as needed, and are purely per form. Fields can be cloned or reused, however, as the form builder allows you to pull in fields from other forms or save common fields as Favorites. | No action is necessary. The migration from Freeform 4 will respect the new architecture and recreate all fields into each form. If you do have a need for a set of common fields, e.g. First Name, Last Name, Email Address, you could open up a form in the form builder and save any number of these as a Favorite. |
| Field Type NamingAffects: All | Multi-word field handles were named with underscores, e.g. opinion_scale. | Multi-word field handles are named with hyphens, e.g. opinion-scale and some have been renamed for clarity. | If you are referencing any of these field types in your template code, update the field type handles of cc_details, confirmation, file_drag_and_drop, multiple_select, opinion_scale, and rich_text to stripe, confirm, file-dnd, multiple-select, opinion-scale, and rich-text, respectively. |
| Field Type NamingAffects: All | Select dropdown fields, checkbox groups, and radio groups were referred to as Select, Checkbox Group, and Radio Group (and select, checkbox_group, and radio_group inside templates), respectively. | To be more intuitive to all users (and consistent with Craft), select dropdown fields, checkbox groups, and radio groups are now referred to as Dropdown, Checkboxes, and Radios (and dropdown, checkboxes, and radios inside templates), respectively. | All Select, Checkbox Group, and Radio Group fields will be migrated to Freeform 5 using the new field type names. If applicable, adjust any templating markup to use dropdown, checkboxes, and radios. |
| Email NotificationsAffects: All | Configuring email notifications for Email fields was done in the property editor for the field. | Configuring email notifications for Email fields is now done in the Notifications tab for each field. This allows you to see an overview of all notifications configured for the form. | No action is necessary. The migration from Freeform 4 will create an Email field in the form layout and configure a notification for it inside the Notifications tab. |
| Submit ButtonsAffects: All | Submit (and Back, Save & Continue Later) buttons were available as special fields to be inserted into the form layout. | Submit, Back, and Save & Continue Later buttons are now automatically inserted into the form layout (as necessary). However, there are manual options for greater control over customization as well. | In order to control the classes and styles of buttons in the form, please use the new buttons approach at template-level, specify attributes for them inside the form builder, or use the manual submit buttons approach. Please see the Submit Button Customization documentation for more information. |
| Freeform Honeypot / Javascript TestAffects: Most | The Freeform Honeypot offers basic protection against forms. The Javascript Test enhances the Honeypot test by performing an action to it that requires javascript to be enabled in the browser. | The Freeform Honeypot and Javascript Test features have been decoupled, overhauled, and set up as integrations. They can now be enabled/disabled and configured per form. The Javascript Test is now a simpler approach that will streamline use with caching or headless implementations. | If you wish to use/continue to use the Honeypot and/or Javascript Test feature, please enable them inside the Integrations area of the Freeform settings. If you're using these features with caching, please review the Caching documentation to update your template code as necessary. If you're using a headless approach, please review the GraphQL documentation to update as necessary. |
| IntegrationsAffects: Most | Integrations were handled in a variety of ways and the experience was inconsistent. | The architecture has changed, and integrations are all set up similarly and can be fine tuned better per form inside the form builder. This approach also allows for easy toggling on/off integrations, so it will be easier to have different ones configured per environment, e.g. Production, Development. Many CRM and Email Marketing integrations now use OAuth for better security as well. | The migration from Freeform 4 will NOT carry forward any integrations. They will need to be set up again. This includes CRM, Email Marketing, Elements (Element Connections), Stripe Payments, Webhooks, Captchas, etc. |
| Sample TemplatesAffects: Most | A wide variety of sample formatting templates were included with Freeform to easily get started with displaying forms. | Freeform 5 continues to offer a wide variety of sample formatting templates and they have been revised and improved. | Not all sample formatting templates were carried over to Freeform 5. The Bootstrap 3, Bootstrap 4, Bootstrap 5 Multipage All Fields and Tailwind 1 formatting templates have been removed. A basic Multipage All Fields formatting template now replaces the Bootstrap 5 Multipage All Fields template. If you're using any of the sample formatting templates, the migration will attempt to update the formatting template to the closest available one, e.g. Tailwind 1 → Tailwind 3, Bootstrap 4 → Bootstrap 5, etc. All sample formatting templates have been revised, however, so you should review how each one displays within your site and adjust CSS, etc as necessary. |
| Dynamic RecipientsAffects: Most | Forms could allow users to select which recipient(s) the form submission should be emailed to using the Dynamic Recipients field type. | Forms can allow users to select which recipient(s) the form submission should be emailed to using any regular option-based field type that is configured as a User Select field inside the form builder. This allows for much greater power and flexibility, and allows values to be stored correctly in the database. | The migration from Freeform 4 will transition any Dynamic Recipient fields to the proper field type they were emulating before. E.g. Dynamic Recipients displayed as a Select dropdown will become a Dropdown field in Freeform 5, and then configured as a User Select notification type inside the Notifications tab of the form builder. |
| Captcha IntegrationsAffects: Most | When using reCAPTCHA v2 Checkbox and hCaptcha Checkbox, a special field became available to insert into your form layout in the form builder. | When using any Captcha, including reCAPTCHA v2 Checkbox and hCaptcha Checkbox, Freeform will automatically insert them into the form before the Submit button. | All Captcha integrations need to be set up again in Freeform 5. If using reCAPTCHA v2 Checkbox or hCaptcha Checkbox, keep in mind that these are automatically handled by Freeform now, once enabled inside the Integrations section of the form builder. |
| Template Directory PathsAffects: Most | Configuring template directories used to be done in one of three settings pages: Formatting Templates, Email Templates and Success Templates. | The Formatting Templates, Email Templates and Success Templates settings pages have now been combined into one unified Template Manager settings page | No action is necessary. |
| Email Marketing IntegrationsAffects: Most | Email Marketing opt-in fields were done with a special field type that did not store any data. | Email Marketing integrations now let you set the target opt-in field. This makes templating cleaner and also stores a record of the data (if they opted in, etc). | All email marketing integrations need to be set up again in Freeform 5. Please keep in mind that when configuring the form inside the form builder, you will need to add a regular Checkbox (or other) field into the form layout and set up the integration to target that field. |
| Form/Field AttributesAffects: Most | Form and field attributes were controlled at template-level with customAttributes and the following parameters: inputClass, submitClass, rowClass, columnClass, labelClass, errorClass, instructionsClass, class, id, name, method, action and useRequiredAttribute. | Form and field attributes are now controlled with the Template Overrides feature, allowing for powerful and flexible fine tuning of attributes and default values, labels, etc. | Please update any references to customAttributes and the attribute control parameters to use the new Template Overrides approach instead. More info... |
| Field Instructions PositioningAffects: Some | To display the field instructions below the field input instead of below the field label when using field.render, you could use the instructionsBelowField parameter. | Freeform 5 no longer includes this parameter. Using the updated formatting template approach and the Template Overrides feature, you can simply use the individual field render methods instead (field.renderLabel, field.renderInput, field.renderInstructions, field.renderErrors). | If your site relies on this feature, please review your custom formatting templates and update as necessary. |
| StripeAffects: Some | The Stripe integration uses the Payment Intents approach and was limited with what it could do. | Freeform 5 uses the newer Stripe Payment Element approach, which includes support for over 40+ payment methods including Stripe Link, Apple Pay, Google Pay, PayPal (within Europe), Bank payments, deferred payments and many other options. We also added the ability to include more than one Stripe payment element field in a single form. When used with conditional rules, you can show/hide one Stripe element at a time (e.g. use a dropdown field to allow the user to choose between one-time or recurring payments). | The migration from Freeform 4 will NOT carry forward the Stripe integration or any field mappings, etc. They will need to be set up and reconfigured again. |
| Checked OptionsAffects: Some | Checking if a field option was checked could be done with option.checked. | This is now done by comparing option.value to field.value in your template. The option.checked property has been removed. | Any use of render on fields should handle this automatically, but if you're manually generating forms, please replace any instances of option.checked with a compare check on option.value to field.value. |
| Success/Error BannersAffects: Some | The defaults for errorClassBanner, errorClassList, errorClassField and successClassBanner plugin options for JS overrides were ff-form-errors, ff-errors, ff-has-errors and ff-form-success | The defaults for errorClassBanner, errorClassList, errorClassField and successClassBanner plugin options for JS overrides are now freeform-form-errors, freeform-errors, freeform-has-errors and freeform-form-success | If you're using AJAX on any form and overriding any of these, please change ff- to freeform- as necessary. |
| Override Field ValuesAffects: Some | Field values could be overrided/selected at template-level with the overrideValues parameter. | Field values can be overrided/selected at template-level with the value parameter in the new Template Overrides feature. | If using this feature, please update any instances of overrideValues in your Form queries to use this new approach. More info... |
| Option Values/LabelsAffects: Few | To display submission data on the front end or in email notification templates, you could use value or valueAsString. However, if you're displaying submission data from a field such as Dropdown or Checkboxes, you did not have control over whether the option value or label was used. | To access field option labels, you can use the new labels and labelsAsString methods. | No action is necessary. However, if you wish to use option Labels instead of Values, adjust any instances of value and valueAsString to labels and labelsAsString as necessary. |
| Surveys & PollsAffects: Few | Freeform 3 & 4 offer an add-on purchase of a Surveys & Polls form type plugin to extend reporting functionality. | This functionality is now included in the Pro edition of Freeform and is no longer a separate plugin. |
|
| Disabling CaptchasAffects: Few | Captchas could be disabled at template-level by using the disableRecaptcha template parameter. | Captchas can be disabled at template-level by using the disableCaptcha template parameter. | The disableRecaptcha template parameter has been removed. Please use disableCaptcha instead. |
| File Drag & Drop CSSAffects: Few | CSS overrides for File Drag & Drop fields started with freeform-file-drag-and-drop. | CSS overrides for File Drag & Drop fields are now shorted to start with freeform-file-dnd. | If using File Drag & Drop fields and overriding CSS styles, please update all references of freeform-file-drag-and-drop to freeform-file-dnd. |
| Duplicate SubmissionsAffects: Few | To prevent duplicate submissions, a Limit Form Submission Rate setting was available in the form builder per form. | That setting has now been renamed to Duplicate Check and all available options have been revised and renamed for clarity as well. | No action is necessary. The migration from Freeform 4 will attempt to update this form setting to the new option name or closest available option. |
| Templating NamespaceAffects: Few | When making Freeform queries, you would need to use craft.freeform.whatever. | Freeform 5 includes a global freeform variable so that queries can be done shorthand as freeform.whatever instead. | No action is necessary. Both craft.freeform.whatever and freeform.whatever will work. You can use whichever you like. |
| Disable/Suppress Emails/IntegrationsAffects: Few | Use the suppress parameter on your form query to suppress email notifications and integrations when editing submissions on the front end. | This parameter has been renamed to disable, and some of the option names for it have changed to fit the updated architecture and naming. It also now includes the ability to disable spam protection features. | If using this feature, please update the parameter to disable and its options: dynamicRecipients, submitterNotifications, and connections parameter names to userSelectNotifications, emailFieldNotifications, and elements, respectively. Additional options are conditionalNotifications, captchas, honeypot, and javascriptTest. If you're using the disableCaptcha and disableHoneypot parameters, please be sure to move that to the new approach within the disable parameter. |
| GraphQLAffects: Few | GraphQL field names and approaches. | Some field names and approaches in GraphQL have been removed or replaced with different architecture. | If using the POST Forwarding or Google Tag Manager features, please see the new Integration approaches. If applying attributes for inputs, labels, errors and instructions, please use FreeformAttributesInterface instead. |
| Form SessionsAffects: Few | Site admins have the option to choose between the following form session contexts: Encrypted Payload, PHP Sessions, and Database Tables | The Freeform Session Context setting has been removed. Encrypted Payload continues to be the assumed and recommended approach, but can still be overrided to PHP Sessions or Database Table deprecated options in project config. | No action is necessary for the vast majority of sites. If your site currently uses PHP Sessions or Database Table, it'll continue to work throughout Freeform 5.x. However, it will be removed for Freeform 6+, so please consider switching to Encrypted Payload instead. |
| HTML/Rich Text FieldsAffects: Few | When manually rendering forms, field.value was used to output the contents of these field types. | When manually rendering forms, field.renderInput is now used to output the contents of these field types. | If your site is manually loading any HTML or Rich Text field types in your templates, please ensure that you are using field.render or field.renderInput to display its contents. |
Updating from 3.x
While updating from Freeform 3.x directly to 5.x is possible, we strongly recommend the following additional steps to help the process go smoother...
Be sure to back up your site files and database before proceeding.
1
Update to the latest 3.x version of Freeform (3.13.x). Be sure to run any available migrations.
2
Update to the latest 4.x version of Freeform (4.1.x) and Craft 4.x. Run any available migrations and confirm that everything appears to work correctly.
3
Proceed to the Updating from 4.x guide below...
Finished!
Updating from 4.x
Be sure to back up your site files and database before proceeding.
1
Review Changes
Carefully review the changelog for Freeform 5.x as well as the new key features/changes table above.
2
Update composer.json File
Edit your project's composer.json file and update the Freeform version to 5.x:
"require": {
"craftcms/cms": "^5.0.0",
"vlucas/phpdotenv": "^5.4.0",
- "solspace/craft-freeform": "^4.0.0",
+ "solspace/craft-freeform": "^5.0.0",
"solspace/craft-calendar": "^5.0.0"
},
3
Get Latest 5.x Package
Get the latest 5.x package of Freeform by running the following command:
php craft update freeform
To get a specific version, run the following command:
php craft update freeform:5.7.0
4
Perform Migration
In your CLI, run one of the following commands:
Update all plugins including Craft
php craft migrate/all
Update Freeform only
php craft migrate --plugin=freeform
We strongly advise against using the Control Panel for updates and migrations. Sites with numerous forms, fields, and submission data may encounter issues using this method.
5
Testing and Cleanup
There will almost certainly be some amount of cleanup required for every site.
- Be sure to apply any changes noted in the key features/changes table above.
- Carefully review and update all Freeform settings, submission data and forms in the form builder.
- Also be sure to review and update your templates and formatting templates (if you have any custom ones) and ensure that everything works correctly and any necessary updates are made.
- If you plan to use the demo templates to review/text/experiment, please reinstall them if you already installed then in an earlier version of Freeform.
6
Migrate Craft 4 Element Titles
If you have upgraded your Craft 4 site to Craft 5, please note that the Craft migration process does not automatically migrate submission Element titles. In Craft 5, Element titles are now stored in the elements_sites table, and the content table which used to store Element titles is no longer used.
While most plugins could include a separate migration script to handle this, Freeform 5 supports both Craft 4 and Craft 5, making this path impossible. Instead, a CLI command has been included that needs to be executed once after upgrading from Craft 4 to Craft 5.
This CLI command is only applicable to sites that have migrated from Craft 4 to Craft 5 while Freeform was installed.
php craft freeform/submissions/fix-titles
Finished!