Upgrading from v4 to v5

Overview

Version 5 of the Advanced Custom Fields plugin introduces many great changes. The main of which is the move away from individual add-ons towards an all inclusive pro version. This article will guide you through the upgrading process and highlight the parts which are important to you.

ACF version 5 is currently available in ACF PRO

Before you update

Please be sure to backup your database before updating to ACF version 5. This simple process takes only a few minutes and ensures that your website can be rolled back quickly and safely if any issues arise.

Please check if you require the PRO version of ACF. If your website is using any of the 4 premium add-ons, you will need a copy of the PRO version, and as a token of our appreciation to your ongoing support, we are giving each existing customer a free version of ACF PRO! Please login to your store account for more info on this special offer.

Please check that all 3rd party plugins which interact with ACF are compatible with ACF5. Please note that the tutorial for creating a field type has been updated with ACF5 compatibility. If you are a developer of a field type, please be sure to read the updated article as the changes should only take a few minutes to implement.

How to update

ACF5 is available in both a free and pro version. If your website is using any of the 4 premium add-ons, please follow the update instructions for the pro version.

Update to ACF5 PRO

  1. Purchase a pro license (or login to your store account to claim your free version!)
  2. Download the ACF PRO plugin
  3. Add the ACF PRO plugin to your website
  4. Activate ACF PRO
  5. Deactivate ACF and any premium ACF Add-ons

Update to ACF5

  1. Navigate to the dashboard’s plugins page
  2. Click the update now button below Advanced Custom Fields

Notes

If a website is upgraded to the free version of ACF5 yet requires pro functionality (add-ons installed), a message will be displayed with prompts to simply rollback to the lastest version 4 ACF plugin.

If you have updated to the free version and require pro, please follow the above pro update instructions to upgrade.

After you update

Once version 5 is activated, you will be prompted to upgrade your database.Please make sure you have backed up your database before running this tool.

After the database has been upgraded you will be redirected to a welcome screen explaining what’s new in version 5.0.0.

Rolling back to version 4

If upgrading to version 5 has caused any issues on your website, please roll back to version 4 whilst you read over this guide. You can do this by simply deactivating and removing the Advanced Custom Fields plugin, downloading an older version from this page and uploading the older version via the dashboard’s plugins page in your WP installation.

Changed to class names

Field class names have changed slightly from field_type-{$type} to acf-field-{$type}. This change was introduced to better optimize JS performance.

If your theme contains custom CSS or JS which relies on the old field class names, you can simply add the following line of code to your functions.php file which will add them back in:

functions.php

add_filter('acf/compatibility/field_wrapper_class', '__return_true');

Changes to field settings

Some field’s settings have changed in ACF5. If you are using register_field_group to register fields via code, don’t worry, ACF5 contains compatibility with the v4 settings, but it is a good idea that you read the following list and make the appropriate changes to your code.

Field Setting Notes
Date Picker date_format Removed setting. All values save in format Ymd
display_format Changed from JS format to PHP format
eg. 'dd/mm/yy' => 'd/m/Y'
return_format Added setting to format the returned value.
This is a PHP format. Defaults to 'd/m/Y'
WYSIWYG media_upload Changed value to numeric
'Yes' => 1
'No' => 0
Image save_format Changed name to return_format
return_format Changed value 'object' => 'array'
File save_format Changed name to return_format
return_format Changed value 'object' => 'array'

Compatibility

Don’t panic if you have not yet updated your field settings code. ACF5 contains a compatibility patch to apply these changes on the fly!

Changes to Options Pages

Previously, the default Options page was added automatically on activation of the Options Page add-on. Now that the Options Page functionality is built into ACF PRO, this will no longer be an automatic process, and the default Options Page will need to be added manually by adding this code to your functions.php file:

acf_add_options_page();

It is good practice to wrap this inside a function_exists if statement and above any defined sub pages like so:

if(function_exists('acf_add_options_page')) { 

	acf_add_options_page();
	acf_add_options_sub_page('Header');
	acf_add_options_sub_page('Footer');

}

Changes to the Date Picker field

Previously, the date picker field contained a setting to allow the save_format to be customized. This customization has been removed, and all values will now be saved in the standard Ymd format. This format allows ACF to add new settings for display and return format. The value can be returned in the same Ymd format or you can change it to something more useful like d/m/Y and reduce template code!

If your website uses a custom save_format setting, don’t panic, ACF will use this to automatically determine the return_format setting and should return the same looking value to your template whether the value was saved before or after the migration!

Changes to naming conventions

Version 5 introduces a more robust naming convention seen throughout the plugin’s code. The most noticeable changes are to field classes and $_POST data.

Description Version 4 Version 5
Field Classes field acf-field
 $_POST prefix $_POST[‘fields’] $_POST[‘acf’]

Update Complete

That’s it! Please be sure to read over the article What’s new in version 5 for the full list of changes in version 5

Hi all. Server maintenance scheduled this Sunday 28th May. Learn more