Связаться с нами
CMS

Как создать поля ACF кодом: регистрация группы на PHP

4 минут на чтение
Иконка чата 0
Иконка глаза 14

Создавать поля через панель удобно, пока группа одна и вы работаете на одном сайте. Когда те же поля нужны на локальной, тестовой и рабочей копиях, ручные настройки легко разъезжаются. ACF позволяет описать группу полей на PHP: тогда её определение хранится рядом с кодом проекта.

Зачем регистрировать группу в PHP

Кодовый вариант помогает команде версионировать структуру полей, переносить её между окружениями и повторно использовать в проектах. Есть и важный нюанс: группа, созданная через PHP, обычно не редактируется как обычная группа на экране ACF. Поэтому выбирайте один источник правды: панель или код, а не два конкурирующих определения одного и того же набора полей.

Официальная документация ACF рекомендует добавлять группы на событии acf/init: к этому моменту функции ACF уже доступны. Файл можно разместить в небольшой собственной теме или плагине сайта. Для проекта с кастомной логикой отдельный плагин часто удобен тем, что поля не исчезают при смене оформления.

Минимальная группа с тремя полями

Ниже — рабочий пример для стандартных записей WordPress. Ключи группы и каждого поля должны быть уникальны в рамках проекта. Имена полей из предыдущих частей сохраняем, чтобы шаблон продолжал получать данные по book_author, book_price и book_summary.

<?php
add_action( 'acf/init', 'codelab_register_book_fields' );

function codelab_register_book_fields() {
    if ( ! function_exists( 'acf_add_local_field_group' ) ) {
        return;
    }

    acf_add_local_field_group( array(
        'key' => 'group_codelab_book_details',
        'title' => 'Данные книги',
        'fields' => array(
            array(
                'key' => 'field_codelab_book_author',
                'label' => 'Автор',
                'name' => 'book_author',
                'type' => 'text',
                'required' => 0,
            ),
            array(
                'key' => 'field_codelab_book_summary',
                'label' => 'Кратко о книге',
                'name' => 'book_summary',
                'type' => 'textarea',
                'rows' => 3,
            ),
            array(
                'key' => 'field_codelab_book_price',
                'label' => 'Цена',
                'name' => 'book_price',
                'type' => 'number',
                'min' => 0,
                'step' => '0.01',
            ),
        ),
        'location' => array(
            array(
                array(
                    'param' => 'post_type',
                    'operator' => '==',
                    'value' => 'post',
                ),
            ),
        ),
        'position' => 'normal',
        'style' => 'default',
    ) );
}

Проверка function_exists() не даёт вызвать функцию регистрации, если ACF отключён. location задаёт место показа формы: здесь это обычные записи. Чтобы показывать её на страницах, укажите значение page; для собственного типа записи используйте его зарегистрированный slug.

Читаем определения по частям

  • key — внутренний уникальный идентификатор группы или поля.
  • label — понятная подпись в админке.
  • name — короткое имя, которое использует шаблон в get_field().
  • type — тип поля, например text, textarea, number или image.
  • location — правила, определяющие, где редактор увидит поля.

Добавим поле ссылки тем же способом:

array(
    'key' => 'field_codelab_book_shop_url',
    'label' => 'Ссылка на магазин',
    'name' => 'book_shop_url',
    'type' => 'url',
),

Этот элемент нужно поместить внутрь массива fields, рядом с остальными полями, не после закрывающей скобки группы.

Что произойдёт с уже сохранёнными данными

Удаление определения группы из кода не обязательно удаляет старые значения из базы, но редактор перестанет видеть форму, а функции ACF могут больше не знать поле как зарегистрированное. Не переименовывайте name без плана миграции: шаблон запрашивает значение по этому имени.

Если структура часто меняется в панели, кодовая регистрация может быть неудобна. Для переноса настроек между средами у ACF есть Local JSON: группы сохраняются в JSON-файлы проекта. А PHP подходит, если определения должны быть частью логики расширения и редактироваться разработчиком.

Как применить пример

  1. Добавьте код в собственный плагин проекта или файл functions.php дочерней темы.
  2. Откройте редактор записи и убедитесь, что поля «Автор», «Кратко о книге» и «Цена» появились.
  3. Заполните значения и используйте PHP-шаблон из второй части для вывода.
  4. Если полей нет, проверьте, активен ли ACF и соответствует ли post_type текущему экрану.

Так вы управляете формой через код, но данные по-прежнему заполняются в привычной панели. В последней части соберём из них законченную карточку и пройдёмся по типичным ошибкам: несовпадающим именам, пустым значениям и небезопасному выводу.

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

  1. ACF для новичков: создаём первые поля в WordPress
  2. Как вывести поля ACF в шаблоне WordPress: get_field() и PHP
  3. Как создать поля ACF кодом: регистрация группы на PHP
  4. Практика ACF: собираем карточку книги и проверяем шаблон

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

Рекомендуемые статьи