Using WordPress Advanced Custom Fields Exports

I wrote about Elliot Condon’s Advanced Custom Fields plugin a while ago (see “Using Advanced Custom Fields for WordPress“), but I thought it might be helpful if I spent some time discussing how to overcome one of the most frustrating tasks related to the plugin: preserving custom field structures across WordPress environments.

The average WordPress developer may edit the custom fields in his or her development environment, write the code to display those fields, then manually re-edit the custom fields on production. Misspell a field name? Congratulations, you’re going to spend some time trying to figure out where you went wrong. The smart developer takes advantage of the Advanced Custom Fields export methods and doesn’t waste time doing the same thing over and over again.

Exporting Custom Fields

Advanced Custom Fields allows you to export your custom field setup in two ways: an XML file compatible with the WordPress Importer (Tools > Import > WordPress) or a PHP file to include in your theme that automatically registers your fields and any add-ons (you could put this in your functions.php file or a separate file that gets included in functions.php). You can export some or all of your custom fields by visiting the Custom Fields > Settings page in the WordPress administration panel.

The Advanced Custom Fields export screen, accessible via Custom Fields > Settings

Each of these export methods have advantages and disadvantages. For instance the XML version has to be imported manually but allows the custom fields to easily be edited, just like in the WordPress environment that created them. The PHP version requires no importing but is more difficult to edit (which can actually be advantageous for client sites).

In practice I’ve found it best to use both versions of the export. The XML file is used (and re-exported after changes are made) by developers and the PHP version is what actually powers the site. It’s a little more work when the developer is committing changes (you are using version control, aren’t you?) but our configuration is protected from “accidental” client changes while remaining flexible when we need to change it ourselves.

Overcoming the Dreaded “Double Field” Issue

One drawback to including the PHP export in your theme is that you’ll likely see duplicates of each custom field – one from your local configuration and one from the included PHP file:

After dealing with this on a few client sites (for the record the second set’s content will be what gets saved) I came up with a simple solution: conditionally include the PHP export based on an environment-specific constant. As you may recall I don’t keep my wp-config.php in my Git repository, so it’s always customized for the environment I’m working in. That makes it the perfect place to specify whether I’m using a local Advanced Custom Fields configuration (development) or my PHP export (staging/production). This is what I came up with:

/** Specify whether to load Advanced Custom Fields configuration from wp_posts (true) or a PHP export file (false) */
define( 'USE_LOCAL_ACF_CONFIGURATION', true );

if ( ! defined( 'USE_LOCAL_ACF_CONFIGURATION' ) || ! USE_LOCAL_ACF_CONFIGURATION ) {
  require_once dirname( __FILE__ ) . '/advanced-custom-fields.php';
}

In wp-config.php, I set the USE_LOCAL_ACF_CONFIGURATION constant to reflect whether or not I want to include advanced-custom-fields.php in my local environment. I’m careful to check that USE_LOCAL_ACF_CONFIGURATION is actually defined – the last thing I want is an undefined constant error popping up in an environment that probably doesn’t even have a local ACF configuration to begin with.

Wrapping Up

The export feature within Advanced Custom Fields is super-useful and the conditional loading makes it a breeze to move between environments; I’ve used this technique on a few projects and I’m continually amazed at how this simple solution was sitting right in front of my face. What about you, how do you (or your team) handle juggling Advanced Custom Fields configurations across environments?

Tags: Advanced Custom Fields, PHP, WordPress, XML