wp_register_ability() │ WP 6.9.0

Регистрирует новую возможность (ability) в Abilities API.

Возможность описывает отдельную операцию: входные данные, результат, функцию выполнения и правила доступа. Зарегистрированные возможности могут находить и запускать другие плагины, REST API, MCP и AI-инструменты.

Для регистрации нужно:

  1. Подключиться к хуку wp_abilities_api_init.
  2. Передать имя возможности и её настройки в wp_register_ability().
  3. Указать функции проверки доступа и выполнения.

Имя возможности должно:

  • Содержать пространство имён, например my-plugin/generate-report.
  • Состоять из строчных латинских букв, цифр, дефисов и /.
  • Описывать действие, например process-payment, а не просто payment.

Категория возможности должна быть зарегистрирована на хуке wp_abilities_api_categories_init раньше самой возможности.

Входные и выходные данные описываются с помощью JSON Schema. WordPress проверяет по этим схемам данные, переданные в возможность, и полученный результат.

Схема обязательна, если возможность принимает или возвращает значение. Поддерживается подмножество JSON Schema Draft 4.

Работает на основе: WP_Abilities_Registry::register()

Хуков нет.

Возвращает

WP_Ability|null.

  • WP_Ability - объект зарегистрированной возможности.
  • null - зарегистрировать возможность не удалось. Например, функция вызвана вне нужного хука, имя или настройки некорректны либо возможность уже зарегистрирована.

Использование

wp_register_ability( $name, $args ): ?WP_Ability;
$name(string) (обязательный)
Уникальное имя возможности с пространством имён, например my-plugin/analyze-text.
$args(array) (обязательный)

Настройки возможности.

  • label(string) (обязательный)
    Понятное человеку название. Рекомендуется переводить через __().

  • description(string) (обязательный)
    Описание назначения возможности и случаев её использования.

  • category(string) (обязательный)
    Ярлык категории. Категорию нужно заранее зарегистрировать через wp_register_ability_category().

  • execute_callback(callable) (обязательный)
    Функция, выполняющая операцию. Получает входные данные и возвращает результат или WP_Error.

  • permission_callback(callable) (обязательный)
    Функция проверки доступа. Получает те же данные, что и execute_callback.

    Должна вернуть:

    • true - выполнение разрешено.
    • false - выполнение запрещено.
    • WP_Error - выполнение запрещено с подробным описанием ошибки.

    Можно проверять права пользователя, API-ключ или состояние системы.

  • input_schema(array)
    JSON Schema входных данных. Используется для автоматической проверки и документирования.

    Если возможность принимает данные, схема обязательна.

  • output_schema(array)
    JSON Schema результата выполнения.

    Если возможность возвращает данные, схема обязательна.

  • meta(array)
    Дополнительные настройки возможности:

    • annotations (array) - подсказки о поведении возможности:
      • readonly (bool|null) - возможность не изменяет данные.
      • destructive (bool|null) - возможность может выполнять разрушительные изменения. false указывает, что изменения только добавляют данные.
      • idempotent (bool|null) - повторный вызов с теми же данными не создаёт дополнительных изменений.
    • public (bool) - делает возможность доступной внешним клиентам, например MCP и AI-агентам. По умолчанию false.
    • show_in_rest (bool) - делает возможность доступной через REST API. По умолчанию наследует значение public.

    Аннотации только описывают поведение для внешних инструментов. Они не ограничивают выполнение возможности.

  • ability_class(string)
    Полное имя класса создаваемого объекта. Класс должен наследовать WP_Ability{}.
    По умолчанию: WP_Ability

Примеры

#1 Регистрация возможности анализа текста

Возможность принимает строку, проверяет её по JSON Schema и получает результат анализа.

add_action( 'wp_abilities_api_init', 'my_plugin_register_abilities' );

function my_plugin_register_abilities(): void {
	wp_register_ability(
		'my-plugin/analyze-text',
		[
			'label'               => __( 'Analyze Text', 'my-plugin' ),
			'description'         => __( 'Performs sentiment analysis on provided text.', 'my-plugin' ),
			'category'            => 'text-processing',
			'input_schema'        => [
				'type'        => 'string',
				'description' => __( 'The text to be analyzed.', 'my-plugin' ),
				'minLength'   => 10,
				'required'    => true,
			],
			'output_schema'       => [
				'type'        => 'string',
				'enum'        => [ 'positive', 'negative', 'neutral' ],
				'description' => __( 'The sentiment result: positive, negative, or neutral.', 'my-plugin' ),
				'required'    => true,
			],
			'execute_callback'    => 'my_plugin_analyze_text',
			'permission_callback' => 'my_plugin_can_analyze_text',
			'meta'                => [
				'annotations' => [
					'readonly' => true,
				],
				'show_in_rest' => true,
			],
		]
	);
}

function my_plugin_analyze_text( string $input ): string|WP_Error {
	$score = My_Plugin::perform_sentiment_analysis( $input );

	if ( is_wp_error( $score ) ) {
		return $score;
	}

	return My_Plugin::interpret_sentiment_score( $score );
}

function my_plugin_can_analyze_text( string $input ): bool|WP_Error {
	return current_user_can( 'edit_posts' );
}

#2 Регистрация категории

add_action( 'wp_abilities_api_categories_init', 'my_plugin_register_categories' );

function my_plugin_register_categories(): void {
	wp_register_ability_category(
		'text-processing',
		[
			'label'       => __( 'Text Processing', 'my-plugin' ),
			'description' => __( 'Abilities for analyzing and transforming text.', 'my-plugin' ),
		]
	);
}

#3 Публикация возможности в REST API

Укажите show_in_rest = true, чтобы возможность можно было запускать через HTTP-запросы к REST API.

'meta' => [
	'show_in_rest' => true,
],

Заметки

Список изменений

С версии 6.9.0 Введена.

Код wp_register_ability() WP 7.0.3

wp-includes/abilities-api.php 
function wp_register_ability( string $name, array $args ): ?WP_Ability {
	if ( ! doing_action( 'wp_abilities_api_init' ) ) {
		_doing_it_wrong(
			__FUNCTION__,
			sprintf(
				/* translators: 1: wp_abilities_api_init, 2: string value of the ability name. */
				__( 'Abilities must be registered on the %1$s action. The ability %2$s was not registered.' ),
				'<code>wp_abilities_api_init</code>',
				'<code>' . esc_html( $name ) . '</code>'
			),
			'6.9.0'
		);
		return null;
	}

	$registry = WP_Abilities_Registry::get_instance();
	if ( null === $registry ) {
		return null;
	}

	return $registry->register( $name, $args );
}

Abilities API (способности)

AI