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!

Notes

The wp-admin field group edit screen will not load data from local json files. This functionality will hopefully soon make it’s way into the plugin.

Manually editing field settings within a local json file will not be visible when editing the field group within the wp-admin edit screen, but will be visible when entering or loading data.

A local json file can be duplicated or manually created, however the key’s used within the json must be unique to avoid overriding of settings.

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.

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