Updating from Freeform 4.x
WARNING
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 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 of these 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. |
Updating from 4.x
DANGER
Be sure to back up your site files and database before proceeding.
"require": {
"craftcms/cms": "^4.0.0",
"vlucas/phpdotenv": "^5.4.0",
- "solspace/craft-freeform": "^4.0.0",
+ "solspace/craft-freeform": "^5.0.0",
"solspace/craft-calendar": "^4.0.0"
},
1
2
3
4
5
6
7
2
3
4
5
6
7
Get the latest 5.x package of Freeform by running the following command:
php craft update freeform1- To get a specific version, run the following command:
php craft update freeform:5.2.01
- To get a specific version, run the following command:
Perform the migration one of two ways:
In your CLI, run one of the following commands (all plugins including Craft, or just Freeform): Recommended
php craft migrate/all1OR
php craft migrate --plugin=freeform1The CLI will then present something like this:
[username@Computer site.test % php craft migrate --plugin=freeform Checking for pending Freeform migrations ... Total 29 new migrations to be applied: m230101_100000_ConvertJsonToLongTextColumns m230101_100010_FF4to5_MigrateForms m230101_100020_FF4to5_MigrateLayout m230101_100030_FF4to5_MigrateNotifications m230101_100050_FF4to5_MigrateIntegrations m230101_100060_FF4to5_MigrateConditionalRules m230101_200000_FF4to5_MigrateData m230101_300100_FF4RemoveOldTables m230224_141036_RemoveRedundantFieldsFromIntegrationsTable m230224_141037_RenameIntegrationTableColumns m230227_102619_MoveCRMIntegrationClasses m230301_124411_MoveMailingListIntegrationClasses m230712_120518_RemoveIntegrationsQueueMailingListFieldIndex m230725_124256_AddCategoryToCrmFields m230809_081815_AddCategoryToMailingListFields m230824_111101_ChangeMailingListsToEmailMarketing m230824_163145_RemoveWebhooksTable m230920_103014_RemoveLastUpdateFromIntegrations m230925_162351_AddEnabledToIntegrations m231020_115409_MigrateIntegrationNamespaces m231116_104621_AlterPaymentTables m231128_142144_AddLinkToPaymentsTable m231206_132139_RemoveLockTable m231219_105754_AddUsersToFormsTable m231229_155623_CreateSurveysPreferencesTable m231230_074448_CreateFieldsTypeGroupsTable m240109_142124_UpdatePageButtonMetadata m240110_111258_ChangeFormFieldRowForeignKey m240111_162954_RemoveStatisticsWidgetFromWidgetsTable Apply the above migrations? (yes|no) [no]:1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
OR
- Proceed to the Craft control panel and click the Finish Updates button when it shows.
WARNING
Sites with a larger number of forms, fields, and submission data could experience issues doing it this way, which is why we strongly recommend the CLI approach instead.
- 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.
Finished!