Local JSON в ACF: переносим группы полей между сайтами

Группу полей можно создать в панели, но тогда настройки хранятся в базе текущего сайта. На локальной копии, тестовом сервере и рабочем сайте эти базы разные. Если менять группу в одном месте и забыть повторить изменения в другом, шаблон может ждать поле, которого редактор на рабочем сайте не видит.

Local JSON сохраняет определения ACF в файлах проекта. Их можно добавить в Git, переносить вместе с кодом и синхронизировать с базой через панель WordPress. Это переносит структуру полей; значения в опубликованных записях остаются данными самого сайта.

Как работает папка acf-json

По умолчанию ACF сохраняет локальные JSON-файлы в папку acf-json темы. Когда группа полей сохраняется через админку, ACF создаёт или обновляет файл с её определением. При загрузке страницы плагин читает найденные определения и может предложить синхронизировать их с базой.

Для начала создайте в активной теме каталог acf-json и убедитесь, что сервер может записывать в него файлы. Далее сохраните группу «Данные книги» в админке и проверьте, появился ли файл с префиксом group_. Не помещайте в этот каталог пароли или значения заполненных записей: JSON описывает настройки групп, а не секреты проекта.

Сохраняем файлы в собственную папку

Если хотите хранить определения в другом месте темы, укажите путь фильтром acf/settings/save_json. Например, чтобы складывать их в acf/field-groups дочерней темы:

<?php
add_filter( 'acf/settings/save_json', 'codelab_acf_save_json_path' );

function codelab_acf_save_json_path( $path ) {
    return get_stylesheet_directory() . '/acf/field-groups';
}

Создайте эту папку и разрешите веб-серверу записывать в неё, если вы собираетесь сохранять группы из панели. Если код должен только загружать JSON из дополнительной папки, добавьте путь через фильтр acf/settings/load_json:

<?php
add_filter( 'acf/settings/load_json', 'codelab_acf_add_json_load_path' );

function codelab_acf_add_json_load_path( $paths ) {
    $paths[] = get_stylesheet_directory() . '/acf/field-groups';
    return $paths;
}

Для стандартной папки темы эти фильтры не нужны. Пример с отдельным путём полезен, когда нужно чётко отделить группы полей от остальных файлов темы. Учитывайте, что get_stylesheet_directory() указывает на активную дочернюю тему; для родительской темы путь будет другим.

Переносим изменения между сайтами

1. Создайте или измените группу полей на локальном сайте.
2. Проверьте, что соответствующий JSON-файл обновился, и добавьте его в Git.
3. Перенесите изменение на тестовый или рабочий сайт обычным процессом развёртывания.
4. В ACF откройте группы полей и вкладку синхронизации, если сайт показывает ожидающее изменение.
5. Сверьте название и дату группы, затем синхронизируйте нужную запись.

Синхронизация обновляет определение группы в базе сайта. Перед ней проверьте, какое определение новее и где были сделаны последние правки. Если кто-то менял эту же группу в админке рабочего сайта, сравните изменения, прежде чем заменять одно другим.

Local JSON или регистрация в PHP

Не создавайте одну и ту же группу одновременно в базе, JSON и PHP: у команды появится несколько источников правды. Выберите один способ, договоритесь, кто меняет поля, и переносите определения согласованно.

Документация

• Local JSON, пути сохранения и синхронизация.
• Регистрация групп полей через PHP.

Продолжение мини-курса

1. Предыдущая часть: собираем карточку книги.
2. Создаём отдельный тип записей «Книги».
3. Списки глав через Repeater.
4. Ищем книги по полям ACF.