Steve Grunwell

Open-source contributor, speaker, and electronics tinkerer

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.

Advanced Custom Fields export screen

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:

An instance of Advanced Custom Fields duplicating fieldsets

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:

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?

Previous

Automatically Recompile Sass upon Deployment Using Git Hooks

Next

Quick Tip: Troubleshooting /etc/hosts issues

14 Comments

  1. Great post, I’ve been using a similar workflow lately for deploying my fields into staging/production. I was getting tired of continually copy+pasting the PHP, so I actually devised a way to get the export to happen automatically, which is proving to be pretty awesome so far. Interested to hear what you think: http://seanbutze.com/automated-exporting-for-advanced-custom-fields/

  2. Byron

    Hi,
    Can this be used by job portals to export into a specific format i.e. Indeed and SimplyHired XML feeds?
    Thanks for your help

    • If you’re looking to export data created with Advanced Custom Fields it should be accessible via the standard WordPress export (Tools › Export) as the data is stored in the post meta. The exports available through Custom Fields › Settings are only the Advanced Custom Fields configuration, not the content. ACF also doesn’t offer control over the export format but the generated file is in the standard WordPress XML structure that can be understood by the WordPress Importer.

      Does that answer your question?

  3. Alexis Duran

    Well the sad thing here is that I can’t even duplicate my field groups on local, I’ve already added the export code generated by PHP into my functions.php I also move the plugin folder to my theme project and I just want to get what I have on my local machine into de project repo.

    Could you suggest me something?

    • You’ll want to export both the PHP and XML versions of your fields. The XML export can be imported via the WordPress importer (Tools > Import) and the PHP version will be included (e.g. require_once or include_once) from within your functions.php file. Does that help clarify things?

  4. Phil Birnie

    Thanks, Steve – good idea. And good seeing you the other evening! Good luck with your talk tomorrow!

  5. Colin

    Thanks Steve.

    This really helped me with my new ACF dev workflow. Much appreciated!

  6. Andrew

    Nice post. Drupal has a similar thing called Features which allows you to have configuration in code.

    In WordPress, if I already have custom fields on a live site (created using the UI) will an exported PHP file from my local dev site override those fields?

    • If there are both locally-defined fields and a PHP configuration, you’ll actually end up with two sets of the fields. Fortunately, that’s just a matter of deleting the local config on staging/production and using the PHP export there instead.

  7. Hey there– super helpful post, was just wondering how I was going to get my fields up to the staging server, from my local dev server. Thanks for sharing.

  8. Paul C

    Thanks for this article, massively helped me out! However, I have a problem with ACF fields which I have no way of knowing how to fix.

    The local site I originally created the ACF fields on has been deleted (lost through computer failure).

    Luckily I had a demo.xml file where all the site data was saved. Problem is, I can’t see the fields created in the ACF admin page.

    Is there a way I can get them back?

    Thanks in advance.

    Paul

    • You should be able to import the demo.xml file (assuming it’s a valid ACF export) using the WordPress Importer (Tools > Import > WordPress) to reconstruct the fields.

      Best of luck, and thanks for the feedback!

  9. omerida

    Thanks for writing this. I’ve started using ACF and was looking for how to easily deploy. The only difference I made is to use a positive:

    define USE_EXPORTED_ACF_CONFIG

    so the test is not a negative boolean, ie I prefer:

    if (defined(‘USE_EXPORTED_ACF_CONFIG’) && USE_EXPORTED_ACF_CONFIG)

    Also I found you can call the register_field_group function from a plugin as well, which is nice if you organize your content types into plugins.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Be excellent to each other.