Updating from Freeform 3.x
Due to the nature of this update we recommend anyone upgrading from Freeform 3.x to do so carefully in a development environment and follow the special instructions below.
Key Changes
The Freeform 4.0 update focuses primarily on Craft 4 compatibility and a number of breaking changes that will allow us to continue to improve Freeform in the future. Please note all key changes below:
Freeform 3.x Behavior | Updated Freeform 4 Behavior | Required Action |
|---|---|---|
Sample formatting templates inconsistly use a mix of |t and |t('freeform') for translations. This caused confusion and annoyance when attempting to translate Freeform's default success/error messages and other language strings. | All sample formatting templates now use |t('freeform') only. | If you're using any of the sample formatting templates included with Freeform, please be sure to move any static translations in xx/site.php to xx/freeform.php. |
| There are a couple of API integrations that are superseded by a newer version, and no longer work. They have been left in place for legacy, but will be removed on each major release. | The old Pardot CRM and Constant Contact email marketing API integrations have been removed. | Please switch to the newer Pardot and Constant Contact integrations if you haven't already, and delete the old legacy ones before upgrading to Freeform 4. |
| Freeform 3.13 introduced a new Success Behavior setting to explicitly handle all possible scenarios for the action Freeform should take when a form is successfully submitted. To preserve legacy of existing install's forms, the success behavior option was set to No Effect, meaning that it would behave exactly as it did prior to Freeform 3.13. This is a redundant option now that 3 other options exists along with the ability to override at template level as well. | All forms with the Success Behavior setting set to No Effect will be updated to Reload Form with Success Message. This will behave somewhat similarly to old behavior, but will not redirect to a different URL upon success. | Please review all forms and set the desired behavior for each in the Success Behavior setting. If you wish to continue to override the behavior at template level, you can do that as well. |
| Freeform 3.11 added the ability to create and update existing file-based email notification templates inside the control panel, making the database-based email notification templates redundant. | UPDATE (July 12, 2022): this decision has been reversed. You can continue to use database-based email notifications in Freeform 4.0.0-beta.14+. | |
| Most of Freeform's sample formatting templates didn't include version numbers. This became problematic to anyone relying heavily on the sample templates whenever we updated existing ones to meet new library versions or standards. | All sample formatting templates now include a library version number on them and also end with .twig extension (e.g. foundation.html is now foundation-6.twig). | Freeform 4 will automatically migrate all existing forms using sample formatting templates to use the new file names. You shouldn't need to change anything. Where this might become an issue is if you are using the formattingTemplate: 'template-name.html' parameter at template level and relying on an older version of the sample template name. |
Single Checkbox fields could contain any value you wish, but the front end templates would render them with a value of 1 (which was converted to the specified value in the form builder when the submission was processed). This was sometimes confusing when manually coding your forms. It also became an issue when using other CRM JS form collectors or features like POST Forwarding, where it would capture the 1 instead of the intended value set in form builder. | In Freeform 4, the value set inside the form builder will now be set as the value of the rendered single checkbox. | No action should be necessary here. If you have a custom module in place to override this behavior, you can likely undo that now. |
| Email field types were stored in the database as an array to maximize their use. It was technically possible to specify multiple versions of an Email field inside a form to collect multiple email addresses for the field (e.g. "Send to Friends") because of this. However, the array of data would often run into issues when mapping data to other integrations or handling it with a custom module, etc, and require workarounds, etc. The trade-off of this functionality gain wasn't worth the frustration it gave many users. | Freeform 4 normalizes Email field types to no longer store data as an array. The migration will comb through your database and convert all values of Email field types (e.g. ["test@x.x"] will become test@x.x). If you were relying on this feature to collect more than one email address, only the first email address will be kept (e.g. ["a@x.x","b@x.x"] will become a@x.x). | Freeform will handle the conversion automatically. However, if you relied on this functionality, it is a breaking change with no alternative option currently (aside from adding multiple Email fields to your forms, one for each email address). If you have a custom module that is working around this in any way, you should be able to disable it now. |
The "From Email" and "From Name" settings inside email notification templates defaulted to include an old way (now removed in Craft 4) of retrieving them via the system settings for email configuration (e.g. craft.app.systemSettings...). | Newly created email notification templates now default to using the newer way (via Project Config), e.g. craft.app.projectConfig...). | If you are using the older approach in existing email notification templates, be sure to update them to the new approach, e.g. craft.app.projectConfig.get('email.fromEmail') |
| Freeform fields are global and all forms share a single database table to store submission data. While this works for the vast majority of sites, one downside to this is that some sites may run out of room and won't be able to create new fields. | Freeform 4 switches this to now have a separate submissions database table for each form. This also helps pave the way to more exciting improvements to the form builder in the future. Fields are still global and available to every form. | No action should be necessary here. Freeform 4 includes a migration script that automatically converts the data to be split into multiple database tables. This process may take a little bit longer if you have a very large site. |
While Freeform fields have been improved throughout 3.x, these changes have never been retroactive. For example, in Freeform 3.12.0, some fields have switched from VARCHAR to TEXT (MySQL column types, not Freeform field types) in order to store more fields in the database and to also allow for more data in each field. Fields created prior to 3.12 will still be VARCHAR and would sometimes require manual changes in the future (to be updated to TEXT, etc). | With the migration necessary to create separate database tables for each form (as mentioned above), all fields will now be TEXT (MySQL column types, not Freeform field types) in the database. | No action should be necessary here. In the rare case where your site has some kind of customization that relies on a MySQL type other than TEXT, you may have to adjust the database manually. |
Run the Freeform 4 Preflight check
Included in Freeform 3.13.7 and up, you can visit the Freeform 4 Preflight page (CP -> Freeform -> Settings -> Craft 4 Preflight) to check whether your site and setup is currently ready for the Freeform 4 changes. It'll make things a lot smoother if you make as many of the changes noted above as possible while on Freeform 3.13.x.
Updating from 3.x
Be sure to backup your site files and database before proceeding.
We strongly recommend updating to the latest Freeform 3.13.x version before proceeding to Freeform 4.x / Craft 4.x, especially when coming from older versions of Freeform 3.x.
1
Carefully review the changelog for Freeform 4.x as well as the new key features/changes table above.
2
Edit your project's composer.json file and update the Freeform version to 4.x:
"require": {
"craftcms/cms": "^4.0.0",
"vlucas/phpdotenv": "^5.4.0",
- "solspace/craft-freeform": "^3.11.0",
+ "solspace/craft-freeform": "^4.0.0",
"solspace/craft-calendar": "^4.0.0"
},
- Run:
composer update - Run the following command or proceed to the Craft control panel and click the Finish Updates button when it shows.
php craft migrate/all
3
Carefully review Freeform inside the control panel and in your templates and ensure that everything works correctly and/or necessary updates to forms/templates/settings are made.
- If you ever use the demo templates to review/test/experiment, please note that we've made some adjustments to them for Freeform 4.x, so you may wish to reinstall them.
- Be sure to apply any changes noted in the key features/changes table above.
Finished!