Регистрация гутенберг блока только на PHP
В WordPress можно создать блок Гутенберга без собственной JavaScript-регистрации, React и сборки через npm. Для этого нужно зарегистрировать динамический блок через register_block_type(), указать PHP-функцию рендера и включить supports.autoRegister.
WordPress сам добавит блок в редактор, покажет серверное превью и создаст простые поля настроек в боковой панели.
Нужен WordPress 7.0 или новее. В более ранних версиях ядра одного render_callback недостаточно, чтобы блок появился в редакторе.
Подход подходит для уведомлений, списков записей, данных из метаполей, карточек автора и других блоков с PHP-разметкой. Работает в классических и блочных темах, если используется редактор блоков.
Как это работает
- На событии init PHP регистрирует тип блока.
supports.autoRegister = trueвключает автоматическую регистрацию в редакторе. Нужен также вызываемыйrender_callback.- Редактор получает HTML через REST API и показывает его как превью. После изменения настроек запрашивает обновлённый HTML.
- На сайте WordPress вызывает ту же PHP-функцию при рендере блока.
Собственный edit() и save() писать не нужно. JavaScript редактора продолжает работать, но его предоставляет WordPress.
Примеры
#1 Минимальный блок
Создадим плагин wp-content/plugins/kama-php-blocks/kama-php-blocks.php:
<?php
/**
* Plugin Name: Kama PHP Blocks
* Requires at least: 7.0
*/
add_action( 'init', 'kama_register_notice_block' );
function kama_register_notice_block() {
register_block_type( 'kama/notice', [
'api_version' => 3,
'title' => 'Уведомление',
'category' => 'widgets',
'icon' => 'info-outline',
'render_callback' => 'kama_render_notice_block',
'supports' => [
'autoRegister' => true,
'html' => false,
],
] );
}
function kama_render_notice_block( $attributes, $content, $block ) {
return sprintf(
'<div %s>Важная информация для посетителей.</div>',
get_block_wrapper_attributes()
);
}
Активируйте плагин и найдите «Уведомление» в списке блоков редактора.
kama/notice- уникальное имя в форматеnamespace/block-name. Используйте строчные латинские буквы, цифры и дефисы; начинайте имя с буквы.title,category,icon- название, категория и иконка. Dashicon указывается без префиксаdashicons-.api_version- версия Block API. Для PHP-only блока редактор использует минимум3, даже если указана более старая версия.html => false- отключает пункт редактирования HTML. Это настройка интерфейса, а не обязательное условие авто-регистрации.
Не ограничивайте регистрацию проверкой is_admin(): блок нужен и на сайте, и в REST API. Успешный вызов register_block_type() возвращает объект WP_Block_Type, при ошибке возвращается false.
Функция рендера
При обычном рендере WordPress передаёт в callback три аргумента:
function kama_render_notice_block( $attributes, $content, $block ) {
return '<div>Содержимое блока</div>';
}
$attributes(массив) - значения атрибутов с учётом схемы и значений по умолчанию.$content(строка) - сохранённая внутренняя разметка. У автоматически зарегистрированного блока без вложенного содержимого обычно пустая.$block(WP_Block{}) - текущий экземпляр блока, в том числе его контекст.
Callback должен вернуть HTML строкой. Для большого шаблона можно использовать ob_start() и вернуть ob_get_clean().
get_block_wrapper_attributes() формирует атрибуты корневого элемента: классы, стили и другие поддерживаемые настройки. Готовую строку вставляют в открывающий тег без повторного esc_attr().
#2 Атрибуты и автоматические поля настроек
Добавим текст сообщения, переключатель и выбор оформления. В первом примере замените обе функции следующим кодом, сохранив строку add_action():
function kama_register_notice_block() {
register_block_type( 'kama/notice', [
'api_version' => 3,
'title' => 'Уведомление',
'category' => 'widgets',
'icon' => 'info-outline',
'attributes' => [
'message' => [
'label' => 'Текст сообщения',
'type' => 'string',
'default' => 'Важная информация для посетителей.',
],
'showTitle' => [
'label' => 'Показывать заголовок',
'type' => 'boolean',
'default' => true,
],
'tone' => [
'label' => 'Оформление',
'type' => 'string',
'enum' => [ 'info', 'success', 'warning' ],
'default' => 'info',
],
],
'supports' => [
'autoRegister' => true,
'html' => false,
],
'render_callback' => 'kama_render_notice_block',
] );
}
function kama_render_notice_block( $attributes, $content, $block ) {
$wrapper_attributes = get_block_wrapper_attributes( [
'class' => 'kama-notice is-tone-' . sanitize_html_class( $attributes['tone'] ),
] );
$title = $attributes['showTitle'] ? '<h2>Обратите внимание</h2>' : '';
return sprintf(
'<div %1$s>%2$s<p>%3$s</p></div>',
$wrapper_attributes,
$title,
esc_html( $attributes['message'] )
);
}
В боковой панели появятся поля для всех трёх атрибутов. Значения tone превратятся в варианты выбора, а CSS-класс is-tone-* позволит оформить каждый вариант.
Какие поля создаются автоматически
| Схема атрибута | Поле в редакторе |
|---|---|
type => 'string' |
Текстовое поле. |
type => 'integer' |
Числовое поле для целых значений. |
type => 'number' |
Числовое поле, допускающее дробные значения. |
type => 'boolean' |
Переключатель. |
Поддерживаемый type вместе с enum |
Выбор из заданных значений. |
labelзадаёт подпись. Без него используется имя атрибута.defaultзадаёт начальное значение. Оно должно соответствоватьtypeи, если есть,enum.- Для авто-поля явно указывайте поддерживаемый
type: одногоenumнедостаточно. - Подписи вариантов
enumформируются из самих значений. Отдельные подписи для них этот механизм не предоставляет.
Примеры числовых атрибутов:
'attributes' => [ 'count' => [ 'label' => 'Количество записей', 'type' => 'integer', 'default' => 5, ], 'price' => [ 'label' => 'Цена', 'type' => 'number', 'default' => 9.99, ], ],
Для переводимых PHP-подписей используйте __( 'Message', 'your-textdomain' ) с текстовым доменом своего плагина.
Когда поле не создаётся
Авто-генерация пропускает атрибут, если:
- У него указан непустой
source, напримерhtml,textилиattribute. - У него
role => 'local'. Такие значения также не сохраняются в содержимом записи. - Его тип отличается от
string,integer,number,boolean. Например, дляarrayиobjectавто-полей нет.
Само объявление атрибута не создаёт RichText, выбор изображения, повторитель, многострочное поле или произвольный компонент интерфейса. Для такого редактора нужен собственный JavaScript.
Схема проверяет типы и допустимые значения перед PHP-рендером, но не заменяет экранирование HTML. Используйте esc_html() для текста, esc_url() для URL, esc_attr() для отдельных HTML-атрибутов и wp_kses_post() для разрешённой HTML-разметки.
#3 Цвета, отступы, типографика и выравнивание
Стандартные возможности оформления включаются отдельно от пользовательских атрибутов. Замените supports в предыдущем примере:
'supports' => [ 'autoRegister' => true, 'html' => false, 'anchor' => true, 'align' => [ 'wide', 'full' ], 'customClassName' => true, 'color' => [ 'text' => true, 'background' => true, 'gradients' => true, ], 'spacing' => [ 'margin' => true, 'padding' => true, ], 'typography' => [ 'fontSize' => true, 'lineHeight' => true, ], ],
WordPress добавит стандартные панели оформления. Доступность конкретных настроек зависит также от темы и theme.json. Для классической темы широкое выравнивание включается поддержкой align-wide.
Оставьте get_block_wrapper_attributes() на корневом элементе: через него применяются выбранные настройки. Атрибуты оформления WordPress добавляет сам, повторно объявлять их в attributes обычно не нужно.
color в supports включает стандартный интерфейс цвета блока. Произвольный атрибут type => 'string' с названием color сам по себе цветовой палитрой не станет.
#4 Регистрация через block.json и отдельный шаблон
PHP-only блок можно описать в block.json. Это рекомендуемый WordPress способ хранения метаданных; JavaScript-файл регистрации всё равно не нужен.
В папке плагина создайте каталог blocks/notice/ с файлами block.json, render.php и style.css.
block.json:
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 3,
"name": "kama/notice",
"title": "Уведомление",
"category": "widgets",
"icon": "info-outline",
"attributes": {
"message": {
"label": "Текст сообщения",
"type": "string",
"default": "Важная информация для посетителей."
}
},
"supports": {
"autoRegister": true,
"html": false,
"color": {
"text": true,
"background": true
}
},
"style": "file:./style.css",
"render": "file:./render.php"
}
В основном файле плагина замените регистрацию из предыдущих примеров:
add_action( 'init', 'kama_register_notice_block' );
function kama_register_notice_block() {
register_block_type( __DIR__ . '/blocks/notice' );
}
Это альтернативный вариант: регистрировать kama/notice одновременно обоими способами не нужно.
render.php:
<div <?php echo get_block_wrapper_attributes( [ 'class' => 'kama-notice' ] ); ?>> <p><?php echo esc_html( $attributes['message'] ); ?></p> </div>
style.css:
.kama-notice {
padding: 1rem;
border-inline-start: 4px solid currentColor;
}
.kama-notice > :first-child {
margin-block-start: 0;
}
.kama-notice > :last-child {
margin-block-end: 0;
}
Поле render создаёт серверный callback автоматически. В шаблоне доступны $attributes, $content и $block. Здесь HTML выводят напрямую: WordPress сам перехватывает вывод файла.
render.php подключается для каждого экземпляра блока. Не объявляйте в нём общие функции и классы: при повторном подключении возникнет ошибка повторного объявления.
Стили и скрипты
| В block.json | При регистрации PHP-массивом | Назначение |
|---|---|---|
style |
style_handles |
CSS для редактора и сайта. |
editorStyle |
editor_style_handles |
CSS только для редактора. |
viewStyle |
view_style_handles |
CSS только для сайта. |
viewScript |
view_script_handles |
Обычный JavaScript для сайта. |
viewScriptModule |
view_script_module_ids |
JavaScript-модуль для сайта. |
В block.json можно указать путь file:./style.css. В PHP-массиве передают массив handles предварительно зарегистрированных ресурсов:
wp_register_style( 'kama-notice', plugins_url( 'blocks/notice/style.css', __FILE__ ), [], '1.0.0' ); register_block_type( 'kama/notice', [ 'title' => 'Уведомление', 'category' => 'widgets', 'style_handles' => [ 'kama-notice' ], 'render_callback' => 'kama_render_notice_block', 'supports' => [ 'autoRegister' => true ], ] );
Этот фрагмент заменяет вызов регистрации внутри callback события init; функция рендера остаётся из примера №1 или №2.
Для поведения на сайте можно добавить viewScript, например для слайдера или раскрывающейся панели. Такой скрипт не создаст интерактивный интерфейс в редакторе: там PHP-only блок показывается как превью.
#5 Динамические данные: последние записи
Блок может получать данные через любые подходящие PHP-функции WordPress. Для списка записей зарегистрируем отдельный тип:
add_action( 'init', 'kama_register_recent_posts_block' );
function kama_register_recent_posts_block() {
register_block_type( 'kama/recent-posts', [
'title' => 'Последние записи',
'category' => 'widgets',
'icon' => 'list-view',
'attributes' => [
'count' => [
'label' => 'Количество записей',
'type' => 'integer',
'default' => 5,
],
],
'supports' => [
'autoRegister' => true,
'html' => false,
],
'render_callback' => 'kama_render_recent_posts_block',
] );
}
function kama_render_recent_posts_block( $attributes, $content, $block ) {
$count = max( 1, min( 20, (int) $attributes['count'] ) );
$posts = get_posts( [
'numberposts' => $count,
'post_status' => 'publish',
] );
if ( ! $posts ) {
return sprintf( '<div %s>Записей пока нет.</div>', get_block_wrapper_attributes() );
}
$html = '';
foreach ( $posts as $item ) {
$html .= sprintf(
'<li><a href="%1$s">%2$s</a></li>',
esc_url( get_permalink( $item ) ),
esc_html( get_the_title( $item ) )
);
}
return sprintf( '<ul %1$s>%2$s</ul>', get_block_wrapper_attributes(), $html );
}
Ограничение 1...20 в callback защищает запрос от чрезмерного количества записей. Список обновляется при новом рендере, без пересохранения страницы. Страничный кеш при этом может продолжать отдавать прежний HTML до обновления кеша.
Данные текущей записи и контекст
Чтобы получить ID записи через экземпляр блока, добавьте в регистрацию:
'uses_context' => [ 'postId', 'postType' ],
В callback можно прочитать метаполе этой записи:
$post_id = (int) ( $block->context['postId'] ?? 0 ); $value = $post_id ? get_post_meta( $post_id, 'reading_time', true ) : ''; return sprintf( '<div %1$s>%2$s</div>', get_block_wrapper_attributes(), esc_html( $value ) );
В block.json соответствующее свойство называется usesContext. Контекст полезен в шаблонах и внутри Query Loop.
При серверном превью редактор передаёт postId. Произвольный контекст предков не переносится в отдельный REST-запрос автоматически: если callback зависит от него, отдельно проверьте совпадение превью с выводом на сайте.
Что ещё можно настроить
PHP-only регистрация сохраняет обычные метаданные блока. Для выбора нужного параметра учитывайте разницу имён:
| PHP-параметр | В block.json | Возможность |
|---|---|---|
description, keywords |
description, keywords |
Описание и слова для поиска блока. |
example |
example |
Пример атрибутов для превью в списке блоков. |
styles |
styles |
Именованные варианты оформления через CSS-классы. |
variations |
variations |
Готовые варианты блока с разными атрибутами. |
parent |
parent |
Ограничение доступности непосредственным родителем. |
ancestor |
ancestor |
Ограничение доступности предком на любой глубине. |
block_hooks |
blockHooks |
Автоматическая вставка рядом с другими блоками. |
Например, вариация уведомления может заранее задавать tone => 'warning'. Свойства parent и ancestor ограничивают место вставки блока, но не создают в нём область для редактирования дочерних блоков.
Полный список аргументов смотрите в register_block_type().
Как блок хранится и выводится
В содержимом записи сохраняется комментарий с именем блока и его настройками, например:
<!-- wp:kama/notice {"message":"Сайт обновлён","tone":"success"} /-->
Значения, совпадающие с default, могут отсутствовать в комментарии: WordPress восстановит их по схеме. Поэтому изменение default затронет и старые экземпляры, в которых значение не было сохранено явно.
Чтобы вывести такую разметку из PHP-шаблона, используйте do_blocks():
echo do_blocks( '<!-- wp:kama/notice {"message":"Сайт обновлён"} /-->' );
Это полезно в классической теме. В блочном шаблоне сам комментарий блока можно разместить прямо в HTML-файле шаблона.
HTML автоматически зарегистрированного блока не сохраняется как резервная копия. После отключения плагина его динамический вывод исчезнет, хотя комментарий с атрибутами останется в содержимом записи.
Ограничения и частые ошибки
-
Блок не появился. Проверьте версию WordPress, загрузку кода на
init, правильностьsupports.autoRegister, вызываемость callback и отсутствие повторной регистрации имени. Проверьте также ограничения доступных блоков в редакторе. -
Превью не загрузилось. Проверьте REST API и PHP-ошибки. Регистрация должна выполняться также при REST-запросе.
-
Настройка есть, оформление не применяется. Проверьте
get_block_wrapper_attributes()на корневом элементе и CSS блока. Выравнивание и часть панелей также зависят от темы. -
Нужны RichText, медиабиблиотека или редактируемые InnerBlocks. Авто-регистрация не создаёт такой интерфейс. Используйте обычный блок со своим JavaScript
edit; PHP-рендер можно сохранить. -
Нужно определить превью через
is_admin(). Эта проверка не подходит: серверное превью загружается через REST API. При необходимости отличайте REST-контекст отдельно, учитывая, что не каждый REST-запрос относится к редактору. - Рендер выполняет дорогие операции. Callback вызывается и для превью, и для каждого экземпляра на сайте. Кешируйте дорогие выборки и внешние запросы; не записывайте данные и не отправляйте уведомления при обычном рендере.
--
Итого
Создание собственных блоков Gutenberg на PHP позволяет расширять редактор WordPress без React, сборки npm и отдельной JavaScript-регистрации. Функция register_block_type() и настройка supports.autoRegister обеспечивают добавление динамического блока, автоматические поля атрибутов и серверное превью. Метаданные можно описать в PHP-массиве или block.json, а HTML формировать через render_callback либо шаблон render.php. Такой подход подходит для разработки простых пользовательских блоков: уведомлений, списков записей, карточек и вывода метаполей.