Local JSON

Overview

Local JSON is a new feature added in version 5 which saves field group and field settings to files within your theme. The idea is similar to caching and both dramatically speeds up ACF and allows for version control over your field settings!

Getting started

To start using the local JSON feature, simply create a new folder in your theme and name it acf-json. This folder must have permissions for the server to read and write (in most cases 755 will work well).

Once this folder exists, each time you save a field group a JSON file will be created / updated with the field group and field settings. The JSON file will be named using the field’s unique key.

Now that the JSON file exists, ACF will load the relevant field group and field settings from this file which reduces the number of database calls during your page load!

Saving explained

Each time you save a field group a JSON file will be created / updated with the field group and field settings. The JSON file will be named using the field’s unique key.

Only 1 save point (folder) exists and can be customized by adding the following code to your theme.

<?php
 
add_filter('acf/settings/save_json', 'my_acf_json_save_point');
 
function my_acf_json_save_point( $path ) {
    
    // update path
    $path = get_stylesheet_directory() . '/my-custom-folder';
    
    
    // return
    return $path;
    
}
 
?>

Loading Explained

During ACF’s initialization procedure, all .json files within the acf-json folder will be loaded. By default ACF looks for a folder within your theme called acf-json, however, this is only 1 of the load points which can be added.

To add a new load point (folder) for ACF to look in, please add the following code to your theme or plugin.

<?php 

add_filter('acf/settings/load_json', 'my_acf_json_load_point');

function my_acf_json_load_point( $paths ) {
    
    // remove original path (optional)
    unset($paths[0]);
    
    
    // append path
    $paths[] = get_stylesheet_directory() . '/my-custom-folder';
    
    
    // return
    return $paths;
    
}

?>

This filter will allow plugin and theme developers to easily register field groups which cannot be edited by clients.

Syncing changes

The real power in ‘local JSON’ is the ability to sync changes. This allows multiple devs to work on a project, use git to push / pull files, and keep all databases synchronized with the latest field group settings!

JSON field groups will be available for sync when either the JSON field group does not exist in the DB, or when the JSON field group contains a higher ‘modified’ value (within the JSON array) than the DB post’s modified date.

When fields groups are detected for synchronization, you will see a new tab above the field group list where you can select the groups to be imported.

acf-pro-sync-available

Security

Please note that in some cases, the use of local JSON may reveal a security hole where field keys and names could be found for vunerability use. To avoid this potential issue, simply do what WordPress does and add a php file called index.php to your acf-json folder and add the following code to it:

<?php

// Silence is golden.

?>

This will prevent anyone from viewing the available files within the folder online. You may also use a .htaccess file or even custom folder permissions too.

Related