Advancing Your WordPress Workflow: Managing ACF Field Groups The Right Way

If you develop custom WordPress themes, there’s no doubt ACF (pro) is in your toolbox. Simply put, it feels like a natural extension for developing custom themes. If you still haven’t picked up this tool, I’d recommend hopping over to their website and see what you’ve been missing.

Out of the box, you get powerful functionality with a fairly intuitive UI for creating field groups. For the most part, these work well when you’re starting out. As you become more advanced with your workflow, you start to notice some problems that aren’t quite solved out of the box.

Why Improve Your Workflow In The First Place?

There are several reasons that mostly boil down to productivity in your personal workflow.

  • Fields are difficult to source control. If you’re using git, committing field groups to source control provides several benefits. Working with multiple developers who all create ACF fields becomes easier when dealing with merges/conflicts. Everything becomes portable with git, much like your main theme files.
  • Managing fields across environments is more intuitive. Currently, you probably sync by manually adding the field on your local/dev/production environments, or using the ACF import/export tool. Doing it this way works, but defining fields as code just makes more sense.
  • Less DB calls/increased performance. When your fields are defined as JSON or PHP code, fields can be queried with less calls to the database. More performance is always a big win
  • Less time is spent using the admin UI. This may or may not be a benefit to some, but spending more time in the text editor can help with context switching and maybe even speed up the process. This benefit mainly applies when using PHP for managing fields.

There are two methods I’ll cover in this article: PHP fields and acf-json. Both have their own pros and cons, and will ultimately be determined by your personal preference. Let’s get to it!

PHP Fields

PHP fields are an easy start since ACF already let’s you export fields as PHP code. You may see this option in the admin under the ‘Tools’ section(ACF Pro).

Notice the ‘Generate PHP’ button on the bottom right

Once you generate the code, it takes the selected fields and turns it into a chunk of usable PHP. Here’s what it looks like:

After that, there’s not much more to it. The code as is should work. All you need to do is include it in your functions.php file and it should start populating the admin area with the fields. From this point on, you edit the PHP file and the changes reflect on the post types/pages. Pretty simple!

Why Use PHP Fields?

If you prefer the text editor over the admin interface, PHP fields are a great option. Another obvious reason is source control with git. If you’re comfortable with PHP, adding/editing fields should be a breeze. There’s nothing much you need to learn to get started, you should be able to use the admin and generate code from there if you get stuck.

You can programmatically organize and create field groups. When generating fields, you get the full power of a programming language at your disposal. You can even use things like partials and traits with ACF builder. There are situations where this can be very useful, unlike acf-json which relies more on the admin UI.

A Better API For PHP Fields

If you checked out the generated code yourself, you may be turned off by the sheer amount of code. Since every option has to be filled out, even if it’s blank, all of the field options add up quickly. These php files can easily reach thousands of lines, which gets messy real quick! Luckily there is an option to dramatically reduce code readability for PHP fields.

Check out ACF Builder, they have their documentation with code samples on their Github page. I won’t go in-depth here, but would like to present it as another viable option.

Additional Resources


As of version 5, acf-json is a built in ACF Pro feature, unlike a library such as ACF Builder. What does acf-json have over PHP fields? Conceptually, they are similar as in they generate code for your fields and allow for easier source control. JSON is stored locally and is built automatically when you make changes using the admin. The biggest difference is the ability to generate code from the admin UI instead of the export page.

Notice the ‘sync’ icon on the right side of each field group.

When you save a field group, a JSON file in a folder named acf-json is generated. When pushing from local to test or production, the sync icons update the admin UI with the JSON fields. Pretty neat, huh? Setting this up is fairly easy too, just read though the additional resource below to get started.

Why acf-json?

I personally prefer acf-json for its simplicity. You use the admin UI like normal, but it generates the code for you. This lets you keep a familiar workflow with the added benefits of local fields. If you prefer being in the text editor more often, PHP fields might be more your speed. If you don’t believe in having more PHP code than necessary, local JSON feels like a more natural approach.

Additional Resources


Setting up a better ACF workflow isn’t so hard after all now is it? If you work on more advanced WordPress sites, there’s a chance that you’ll come across both of these methods. In my opinion, you should learn both and find out which one you prefer! There’s no real right or wrong answer here, these are simply two options to give you more control over your fields. If you haven’t heard of these concepts before, I hope I at least introduced the idea to your workflow!