Регистрация гутенберг блока только на PHP

В WordPress можно создать блок Гутенберга без собственной JavaScript-регистрации, React и сборки через npm. Для этого нужно зарегистрировать динамический блок через register_block_type(), указать PHP-функцию рендера и включить supports.autoRegister.

WordPress сам добавит блок в редактор, покажет серверное превью и создаст простые поля настроек в боковой панели.

Нужен WordPress 7.0 или новее. В более ранних версиях ядра одного render_callback недостаточно, чтобы блок появился в редакторе.

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

Как это работает

  1. На событии init PHP регистрирует тип блока.
  2. supports.autoRegister = true включает автоматическую регистрацию в редакторе. Нужен также вызываемый render_callback.
  3. Редактор получает HTML через REST API и показывает его как превью. После изменения настроек запрашивает обновлённый HTML.
  4. На сайте 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. Такой подход подходит для разработки простых пользовательских блоков: уведомлений, списков записей, карточек и вывода метаполей.