Обзор
Local JSON — полезная функция, которая сохраняет группы полей, типы записей, таксономии и страницы опций в виде JSON-файлов внутри вашей темы. Эта идея похожа на кэширование: она значительно ускоряет работу ACF и позволяет хранить настройки полей под контролем версий!
Начало работы
Чтобы начать использовать функцию Local JSON, создайте в своей теме новую папку и назовите её acf-json. Эта папка должна быть доступна серверу для записи (в большинстве случаев хорошо подойдут права 755).
После создания папки и сохранения группы полей, типа записи, таксономии или страницы опций в административной панели ACF ACF также сохранит этот объект в JSON-файл внутри папки.
После создания JSON-файла ACF будет загружать соответствующие настройки из него, уменьшая количество обращений к базе данных при загрузке страницы и повышая производительность.
Как работает сохранение
При каждом сохранении группы полей, типа записи, таксономии или страницы опций будет создаваться или обновляться JSON-файл с настройками сохраняемого объекта. По умолчанию имя JSON-файла формируется на основе уникального ключа этого объекта.
Для настройки путей сохранения JSON можно использовать несколько фильтров. Чтобы задать единый путь сохранения для всех JSON-файлов, используйте фильтр acf/settings/save_json:
<?php
function my_acf_json_save_point( $path ) {
return get_stylesheet_directory() . '/my-custom-folder';
}
add_filter( 'acf/settings/save_json', 'my_acf_json_save_point' );
Начиная с ACF 6.2, для фильтра acf/settings/save_json также доступны несколько модификаторов, позволяющих указывать разные пути для разных файлов:
acf/settings/save_json/key={$key}Ключ группы полей, типа записи, таксономии или страницы опций интерфейса.acf/settings/save_json/name={$name}Имя группы полей, типа записи, таксономии или страницы опций интерфейса.acf/settings/save_json/type={$post_type}Может иметь одно из следующих значений:acf-field-group,acf-post-type,acf-taxonomyилиacf-ui-options-page.
Эти фильтры позволяют точно управлять местом сохранения JSON-файла на основе имени, ключа или типа записи сохраняемого объекта. Если для одного файла подходят несколько путей, будет выбран наиболее специфичный путь — например, фильтр acf/settings/save_json/key={$key} переопределит фильтр acf/settings/save_json/name={$name} и так далее.
Например, с помощью следующего фильтра можно сохранять все пользовательские типы записей ACF в отдельную папку:
<?php
function my_acf_cpt_save_folder( $path ) {
return get_stylesheet_directory() . '/acf-json/post-types';
}
add_filter( 'acf/settings/save_json/type=acf-post-type', 'my_acf_cpt_save_folder' );
В ACF 6.2 также появился новый фильтр acf/json/save_paths с двумя параметрами. Первый параметр — массив всех возможных путей сохранения текущего файла, а второй — массив, содержащий все настройки группы полей, типа записи, таксономии или страницы опций. Это позволяет использовать одну функцию для нескольких объектов и изменять путь в зависимости от таких параметров, как имя объекта:
<?php
function custom_acf_json_save_paths( $paths, $post ) {
if ( $post['title'] === 'Настройки темы' ) {
$paths = array( get_stylesheet_directory() . '/options-pages' );
}
if ( $post['title'] === 'Поля настроек темы' ) {
$paths = array( get_stylesheet_directory() . '/field-groups' );
}
return $paths;
}
add_filter( 'acf/json/save_paths', 'custom_acf_json_save_paths', 10, 2 );
Если вы используете пользовательский путь сохранения и хотите, чтобы ACF также загружал файлы из этого пути, добавьте этот путь в фильтр acf/settings/load_json, как показано ниже.
Чтобы настроить имя файла, можно использовать новый фильтр acf/json/save_file_name. Ниже приведён короткий пример изменения имени файла так, чтобы оно соответствовало имени группы полей, типа записи или таксономии:
<?php
function custom_acf_json_filename( $filename, $post, $load_path ) {
$filename = str_replace(
array(
' ',
'_',
),
array(
'-',
'-'
),
$post['title']
);
$filename = strtolower( $filename ) . '.json';
return $filename;
}
add_filter( 'acf/json/save_file_name', 'custom_acf_json_filename', 10, 3 );
Как работает загрузка
Все файлы .json внутри папки acf-json загружаются во время инициализации ACF. По умолчанию ACF ищет в вашей теме папку с названием acf-json. Однако это лишь одна из точек загрузки, которые можно добавить.
Чтобы добавить новую точку загрузки (папку), из которой ACF будет загружать файлы, добавьте следующий код в тему или плагин.
<?php
function my_acf_json_load_point( $paths ) {
// Удалить исходный путь (необязательно).
unset($paths[0]);
// Добавить новый путь и вернуть массив.
$paths[] = get_stylesheet_directory() . '/my-custom-folder';
return $paths;
}
add_filter( 'acf/settings/load_json', 'my_acf_json_load_point' );
Этот фильтр позволяет разработчикам плагинов и тем легко регистрировать группы полей, типы записей, таксономии или страницы опций, которые клиенты не смогут редактировать.
Синхронизация изменений
Настоящая сила функции Local JSON в ACF — возможность синхронизировать изменения. Благодаря этому несколько разработчиков могут работать над проектом, использовать git для отправки и получения файлов, а также поддерживать все базы данных синхронизированными с последними версиями групп полей, типов записей, таксономий и страниц опций.
Объекты, сохранённые в JSON, будут доступны для синхронизации, если они отсутствуют в базе данных или если значение «modified» в версии JSON (внутри JSON-массива) выше даты изменения записи, сохранённой в базе данных.
Когда будут обнаружены объекты для синхронизации, над таблицей со списком появится новая вкладка, где можно выбрать объекты для импорта.
Безопасность
Если вы хотите скрыть JSON-файлы от общего доступа, просто добавьте пустой файл index.php в папку acf-json, чтобы запретить просмотр содержимого каталога. WordPress использует такой же способ, чтобы скрыть папку wp-content/themes. Они ещё любят добавлять сообщение 👍.
index.php
<?php // Тишина — золото.
Обновлено: 30.09.2026