Стандартных полей WordPress хватает до первого кастомного проекта. Нужно вывести характеристики товара в карточку, добавить галерею к странице или прикрутить блок с условиями доставки, и сразу упираешься в ограничения редактора: заголовок, текст, рубрики, всё.

Выход есть, и он не ACF Pro за $149 в год. Кастомные мета-боксы добавляют произвольные поля прямо в интерфейс редактирования записи без визуального конструктора и без десятка ненужных модулей. CMB2 делает ровно это: даёт PHP-API для описания мета-боксов кодом, который лежит в системе контроля версий, а не в базе.

Ниже полный цикл: от установки плагина до вывода данных на фронтенде. К концу статьи получите рабочий файл мета-боксов, который адаптируется под любой тип контента от страниц до товаров WooCommerce.

💡 Быстрый обзор:

• Установите CMB2 из каталога WordPress.org: плагин бесплатный и ставится в два клика.
• Создайте файл metaboxes.php в папке темы и опишите нужные поля через хук cmb2_admin_init.
• Подключите файл в functions.php одной строкой require_once и проверьте мета-бокс в админке.
• Выведите сохранённые данные на фронтенде через get_post_meta() с правильным экранированием.

Что такое CMB2: код вместо визуального конструктора

CMB2, библиотека для разработчиков, которая создаёт мета-боксы, кастомные поля и формы в WordPress. Из коробки она поддерживает десятки типов полей: текст, WYSIWYG-редактор, загрузка файлов, выбор даты, цветопикер, радиокнопки, выпадающие списки, повторители и группы.

Главное отличие от ACF: у CMB2 нет визуального построителя. Все мета-боксы описываются в PHP-файлах темы. Для разработчика это плюс: конфигурация лежит в Git, её нельзя случайно удалить через админку, а перенос между staging и production сводится к деплою кода. При этом CMB2 полностью бесплатна, тогда как ACF Pro обойдётся в $149 в год за повторяемые поля и группы.

Библиотека активно поддерживается с 2014 года. На WordPress.org у плагина рейтинг 5 звёзд и более 300 000 активных установок. GitHub-репозиторий получает регулярные обновления: последний релиз закрыл совместимость с PHP 8.4 и WordPress 6.7. Это не abandoned-проект, который бросят через полгода.

Шаг 1: Устанавливаем плагин

Зайдите в Плагины → Добавить новый, введите «CMB2» в поиске и нажмите «Установить». После активации плагин загружает движок, но сам по себе ничего не меняет в админке, мета-боксы появятся только после того, как вы их опишете в коде.

Если подключаете CMB2 вручную внутри темы без установки через админку, добавьте в начало functions.php:

1
require_once __DIR__ . '/cmb2/init.php';

Два важных момента. Первое: init.php должен загружаться как можно раньше, вне любых хуков. Не оборачивайте его в проверки if ( ! class_exists(..., CMB2 сам обрабатывает конфликты повторной загрузки. Второе: при ручном подключении обновления CMB2 придётся делать вручную, в отличие от автообновлений через админку.

Шаг 2: Пишем файл мета-боксов

Создайте папку cmb2-metaboxes в корне дочерней темы и файл metaboxes.php внутри неё. В этом файле соберём все определения полей.

Ниже рабочий код, который добавляет текстовый редактор, короткое описание и селект с бейджем к товарам WooCommerce. Скопируйте его в metaboxes.php:

1
add_action( 'cmb2_admin_init', 'sdstudio_register_metaboxes' );
2
 
3
function sdstudio_register_metaboxes() {
4
 
5
    $prefix = '_sdstudio_';
6
 
7
    $cmb = new_cmb2_box( array(
8
        'id'           => 'product_extra_info',
9
        'title'        => __( 'Дополнительная информация о товаре', 'cmb2' ),
10
        'object_types' => array( 'product' ),
11
        'context'      => 'normal',
12
        'priority'     => 'high',
13
        'show_names'   => true,
14
    ) );
15
 
16
    $cmb->add_field( array(
17
        'name'    => __( 'Описание для карусели на главной', 'cmb2' ),
18
        'desc'    => __( 'Текст, который будет показан в слайдере товаров.', 'cmb2' ),
19
        'id'      => $prefix . 'carousel_desc',
20
        'type'    => 'wysiwyg',
21
        'options' => array(
22
            'textarea_rows' => 5,
23
        ),
24
    ) );
25
 
26
    $cmb->add_field( array(
27
        'name' => __( 'Короткое описание', 'cmb2' ),
28
        'desc' => __( 'Одна строка — для карточки товара в сетке.', 'cmb2' ),
29
        'id'   => $prefix . 'short_desc',
30
        'type' => 'textarea_small',
31
    ) );
32
 
33
    $cmb->add_field( array(
34
        'name' => __( 'Бейдж товара', 'cmb2' ),
35
        'desc' => __( 'Метка «Новинка», «Хит» или «Распродажа».', 'cmb2' ),
36
        'id'   => $prefix . 'badge',
37
        'type' => 'select',
38
        'show_option_none' => true,
39
        'options'          => array(
40
            'new'   => __( 'Новинка', 'cmb2' ),
41
            'hit'   => __( 'Хит', 'cmb2' ),
42
            'sale'  => __( 'Распродажа', 'cmb2' ),
43
        ),
44
    ) );
45
 
46
}

Что здесь происходит: хук cmb2_admin_init срабатывает при загрузке админки и регистрирует мета-бокс на странице редактирования товара. new_cmb2_box() создаёт контейнер с заголовком «Дополнительная информация о товаре», а три вызова add_field() добавляют в него поля: WYSIWYG-редактор, компактное текстовое поле и выпадающий список с предустановленными вариантами. Каждое поле получает уникальный id с префиксом _sdstudio_, это исключает конфликты с другими плагинами.

Если вместо WooCommerce нужны обычные страницы, замените 'object_types' => array( 'product' ) на 'object_types' => array( 'page' ). Для нескольких типов контента укажите их списком: array( 'page', 'post' ).

Полный список типов полей смотрите в официальной документации CMB2 на GitHub. Из коробки доступны десятки вариантов: от обычного текста и WYSIWYG-редактора до загрузки файлов, цветопикера, радиокнопок и таксономий. Какой тип выбрать под конкретную задачу, решайте по документации, а не по догадкам.

Шаг 3: Подключаем в functions.php

Теперь нужно загрузить созданный файл. Откройте functions.php дочерней темы и добавьте одну строку перед закрывающим тегом ?>, или в конец файла, если тега нет:

1
require_once __DIR__ . '/cmb2-metaboxes/metaboxes.php';

Перед добавлением кода сделайте бэкап functions.php. Синтаксическая ошибка в require_once уронит сайт с фатальной ошибкой PHP, и восстановить файл можно будет только через FTP или хостинг-панель. После сохранения откройте любой товар в админке и убедитесь, что мета-бокс «Дополнительная информация о товаре» появился под редактором контента.

Заполните тестовые поля и нажмите «Обновить». CMB2 автоматически сохраняет данные в таблицу wp_postmeta. Никаких дополнительных вызовов хука save_post не требуется: библиотека перехватывает сохранение записи и обрабатывает свои поля сама.

Шаг 4: Выводим данные на фронтенд

Данные сохранены в базе, осталось показать их посетителям. Откройте файл темы, отвечающий за страницу товара, обычно это single-product.php или content-single-product.php. Добавьте код внутрь цикла WordPress:

1
<?php
2
$carousel_desc = get_post_meta( get_the_ID(), '_sdstudio_carousel_desc', true );
3
$badge         = get_post_meta( get_the_ID(), '_sdstudio_badge', true );
4
 
5
if ( ! empty( $carousel_desc ) ) : ?>
6
    <div class="product-carousel-desc">
7
        <?php echo wp_kses_post( $carousel_desc ); ?>
8
    </div>
9
<?php endif; ?>
10
 
11
<?php if ( ! empty( $badge ) ) : ?>
12
    <span class="product-badge product-badge--<?php echo esc_attr( $badge ); ?>">
13
        <?php echo esc_html( $badge ); ?>
14
    </span>
15
<?php endif; ?>
16

Разбор: get_post_meta() извлекает значение по ID поля. Для WYSIWYG-поля используйте wp_kses_post(), она пропускает разрешённые HTML-теги и фильтрует потенциально опасные. Для обычного текста или селекта достаточно esc_html(), которая превращает спецсимволы в HTML-сущности и исключает XSS.

Если мета-бокс создан для страниц ('object_types' => array( 'page' )), разместите этот же код в page.php или content-page.php. Механика та же: get_post_meta() внутри цикла, экранирование по типу поля.

Видео: CMB2 от установки до рабочего мета-бокса

В этом 20-минутном туториале автор проходит полный цикл: установка, создание полей, подключение файла и вывод данных на фронтенд. Полезно посмотреть, если текстовая инструкция оставила пробелы.

⁉️🤔 Частые вопросы

Чем CMB2 отличается от ACF?

ACF даёт визуальный конструктор полей прямо в админке: можно собрать мета-бокс без единой строки кода. CMB2 требует описывать поля в PHP-файлах темы. Для разработчика, который хранит конфигурацию в Git, CMB2 удобнее: мета-боксы не зависят от состояния базы, их нельзя случайно удалить через админку, а перенос между staging и production сводится к деплою кода. ACF Pro стоит от $149 в год за повторяемые поля и группы, CMB2, бесплатно.

Можно ли использовать CMB2 без установки плагина?

Да. Скопируйте папку CMB2 внутрь темы и подключите init.php в functions.php, как показано в шаге 1. Такой подход удобен для премиум-тем, которые должны работать сразу после активации без требования установить сторонний плагин. Минус: обновления CMB2 придётся делать вручную при каждой новой версии.

Работают ли поля CMB2 в Gutenberg-редакторе?

Да, мета-боксы CMB2 выводятся под редактором Gutenberg в привычном виде, в секции под контентом. Но из коробки они не интегрируются в блоки редактора. Если нужно встроить поле прямо в блок, потребуется дополнительная разработка через CMB2 API и register_block_type().

Что делать, если мета-бокс не появляется в админке?

Проверьте три вещи. Первое: совпадает ли object_types с типом редактируемой записи, для товаров WooCommerce нужно 'product', не 'post'. Второе: нет ли синтаксической ошибки в PHP, включите WP_DEBUG в wp-config.php и посмотрите лог. Третье: не конфликтует ли префикс id полей с другим плагином, используйте уникальный префикс вроде _sdstudio_.

Можно ли сделать повторяющиеся группы полей?

Да. CMB2 поддерживает повторяемые поля через флаг 'repeatable' => true и повторяемые группы через $cmb->add_group_field(). Группа позволяет добавить блок «Характеристика: значение» и создавать новые экземпляры кнопкой «Добавить строку» прямо в админке.

Работает ли CMB2 с мультисайтом?

Да, плагин полностью совместим с WordPress Multisite. Мета-боксы можно регистрировать глобально в functions.php активной темы сети или по-отдельности для каждого сайта. Вызов get_post_meta() работает одинаково в обоих режимах.

CMB2 или ACF: какой подход выбрать под вашу задачу

CMB2 закрывает ровно одну задачу, создание кастомных мета-боксов через код, с хранением конфигурации в файлах темы, а не в базе. Выбор сводится к вашему рабочему процессу, а не к абстрактному «что лучше».

• Если вы разработчик и храните всю конфигурацию проекта в Git, берите CMB2. Мета-боксы живут в metaboxes.php, деплоятся вместе с темой и не требуют синхронизации базы между staging и production.

• Если вам нужен визуальный построитель, повторяемые гибкие поля и готовые блоки для Gutenberg без строки кода, берите ACF Pro. Подписка от $149 ежегодно окупается скоростью прототипирования.

• Если проект уже использует CMB2 и мета-боксы работают стабильно, оставайтесь на нём. Библиотека не abandoned, не требует срочной миграции и регулярно получает обновления совместимости.

Попробуйте оба подхода на тестовом сайте: соберите один и тот же мета-бокс в CMB2 и в ACF. Разница в подходе станет очевидной за 20 минут. А какой инструмент используете вы, напишите в комментариях.