Стандартних полів 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 хвилин. А який інструмент використовуєте ви, напишіть у коментарях.