Abilities API в WordPress 6.9

WordPress 6.9 добавляет Abilities API - это новая система, которая позволяет плагинам, темам и ядру WordPress описывать свои функции в едином, понятном для машин формате.

Теперь любая возможность сайта можно зарегистрировать так, чтобы ее можно было найти, проверить и вызвать из разных мест: PHP, через REST API и в будущих AI-инструментах.

Этот API входит в инициативу "AI Building Blocks for WordPress" и создает основу для работы AI-агентов и автоматизации. Благодаря ему внешние системы и разработчики смогут точно понимать, какие функции доступны на сайте, как именно они работают.

Оглавление:

Что такое Abilities API?
Компоненты API:
Основные понятия
Использование abilities
Базовый пример использования
Более сложный пример регистрации
Категории
PHP Функции и Хуки API
Функции
Хуки
Naming Convention
Ability Name Convention
Category Slug Convention
Проверка и получение abilities
Обработка ошибок
Валидация через JSON Schema (REST API)
Использование REST API эндпоинтов
Обратная совместимость
Дополнительные материалы

Что такое Abilities API?

Abilities API в WordPress предоставляет стандартизированный способ регистрации отдельных единиц функциональности внутри сайта. Эти единицы представляют собой конкретные действия или возможности, которые могут выполнять компоненты, с четко определенными входами, выходами и разрешениями.

API действует как центральный реестр, упрощая взаимодействие между разными частями WordPress, сторонними плагинами, темами и внешними системами (например, AI-агентами), помогая им понимать доступные на сайте возможности.

Ability (способность) - это автономная единица функциональности с четко определенными входными и выходными данными, правами доступа и логикой выполнения.

Цели и преимущества

Стандартизация: Единый способ описывать функциональность сайта.
Валидация: Встроенная проверка входных и выходных данных через JSON Schema.
Безопасность: Гибкий контроль доступа через permission callbacks.
Расширяемость: Простая регистрация способностей в любом плагине или теме.
Обнаружение: Функциональность легко открывается для AI и автоматизации.
AI-ориентированность: Машиночитаемый формат для интеграции с AI-агентами.

Регистрируя abilities через Abilities API, разработчики могут:

Создавать функциональность со стандартизированными интерфейсами.
Определять проверки прав доступа и коллбеки выполнения.
Организовывать abilities по логическим категориям.
Валидировать входные и выходные данные.
Автоматически публиковать abilities через REST API эндпоинты.

Примеры использования

AI-интеграции: Позволить агентам открывать и выполнять действия на сайте.
Взаимодействие плагинов: Плагины могут находить и использовать функциональность друг друга.
Инструменты автоматизации: Программный доступ к возможностям сайта.
API-документация: Самодокументируемая функциональность с валидацией схем.
Инструменты разработчика: Стандартизированный способ экспонировать функции плагинов.

Основные понятия

Ability (способность): Отдельная функциональная единица с уникальным именем в формате namespace/ability-name. Каждая способность имеет человекочитаемое имя, описание, определения входных и выходных данных (через JSON Schema), категорию, необязательные разрешения и функцию-обработчик. Каждая зарегистрированная способность является экземпляром WP_Ability.
Category (категория): Способ группировать связанные способности. Каждая способность должна принадлежать ровно одной категории. Категории имеют слаг, метку и описание. Каждая категория является экземпляром WP_Ability_Category.
Registry (реестр): Центральный синглтон WP_Abilities_Registry, хранящий все зарегистрированные способности. Он предоставляет методы для регистрации, удаления, поиска и выборки способностей. Аналогично, WP_Abilities_Category_Registry управляет категориями.
Callback (обработчик): PHP-функция или метод, который выполняется при вызове способности через WP_Ability::execute().
Schema (схема): JSON Schema для входных данных (input_schema) и выходных (output_schema). Это обеспечивает валидацию и помогает агентам понимать, как использовать способность.
Permission Callback (проверка разрешений): Необязательная функция, определяющая, может ли текущий пользователь выполнить способность.
Namespace (пространство имен): Первая часть имени способности (до слэша). Обычно совпадает с названием плагина или компонента, который регистрирует способность.

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

Abilities должны регистрироваться в хук wp_abilities_api_init. Попытка регистрации abilities вне этого хука приведет к уведомлению _doing_it_wrong(), и регистрация ability завершится неудачно.

Подробнее: https://github.com/WordPress/abilities-api/blob/trunk/docs/php-api.md

Базовый пример использования

Пример ниже предназначен для реализации в плагине, но его также можно адаптировать для файла functions.php темы:

// 1. Определяем callback функцию для абилити
function my_plugin_get_site_title( array $input = array() ): string {
	return get_bloginfo( 'name' );
}

// 2. Регистрируем абилити
add_action( 'wp_abilities_api_init', 'my_plugin_register_abilities' );
function my_plugin_register_abilities() {
	wp_register_ability( 'my-plugin/get-site-title', array(
		'label'               => __( 'Get Site Title', 'my-plugin' ),
		'description'         => __( 'Retrieves the title of the current WordPress site.', 'my-plugin' ),
		'category'            => 'site-info',
		'input_schema'        => [
			'type'                 => 'object',
			'properties'           => [],
			'additionalProperties' => false,
		],
		'output_schema'       => [
			'type'        => 'string',
			'description' => 'The site title.',
		],
		'execute_callback'    => 'my_plugin_get_site_title',
		'permission_callback' => '__return_true', // Everyone can access
		'meta'                => [
			'show_in_rest' => true, // включить поддержку REST API
		],
	) );
}

// 3. Затем, можно получить и выполнить абилити
add_action( 'admin_init', 'my_plugin_use_ability' );
function my_plugin_use_ability() {
	$ability = wp_get_ability( 'my-plugin/get-site-title' );
	if ( ! $ability ) {
		return;
	}

	$site_title = $ability->execute();
	if ( is_wp_error( $site_title ) ) {
		error_log( 'Execution error: ' . $site_title->get_error_message() );
		return;
	}

	// $site_title теперь содержит результат
	echo 'Site Title: ' . esc_html( $site_title );
}

Более сложный пример регистрации

Пример с более сложными схемами входных и выходных данных, валидацией и обработкой ошибок:

add_action( 'wp_abilities_api_init', 'my_register_text_analysis_ability' );

function my_register_text_analysis_ability() {
	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'       => 'object',
				'required'   => [ 'text' ],
				'properties' => [
					'text'    => [
						'type'        => 'string',
						'description' => __( 'The text to analyze.', 'my-plugin' ),
						'minLength'   => 1,
						'maxLength'   => 5000,
					],
					'options' => [
						'type'       => 'object',
						'properties' => [
							'include_keywords' => [
								'type'        => 'boolean',
								'description' => __( 'Whether to extract keywords.', 'my-plugin' ),
								'default'     => false,
							],
						],
					],
				],

			],
			'output_schema'       => [
				'type'       => 'object',
				'properties' => [
					'sentiment'  => [
						'type'        => 'string',
						'enum'        => [ 'positive', 'neutral', 'negative' ],
						'description' => __( 'The detected sentiment.', 'my-plugin' ),
					],
					'confidence' => [
						'type'        => 'number',
						'minimum'     => 0,
						'maximum'     => 1,
						'description' => __( 'Confidence score for the sentiment.', 'my-plugin' ),
					],
					'keywords'   => [
						'type'        => 'array',
						'items'       => [
							'type' => 'string',
						],
						'description' => __( 'Extracted keywords (if requested).', 'my-plugin' ),
					],
				],
			],
			'execute_callback'    => 'my_plugin_analyze_text',
			'permission_callback' => fn() => current_user_can( 'edit_posts' ),
		]
	);
}

/**
 * Callback for analyze-text ability.
 */
function my_plugin_analyze_text( array $input ): array {
	$text             = $input['text'];
	$include_keywords = $input['options']['include_keywords'] ?? false;

	// Perform analysis (simplified example).
	$sentiment  = 'neutral';
	$confidence = 0.75;

	$result = [
		'sentiment'  => $sentiment,
		'confidence' => $confidence,
	];

	if ( $include_keywords ) {
		$result['keywords'] = [ 'example', 'keyword' ];
	}

	return $result;
}

Категории

Каждая ability должна быть привязана к категории. Категории повышают удобство поиска и помогают группировать связанные abilities. Категории должны регистрироваться заранее, через хук wp_abilities_api_categories_init.

// Cначала регистрируем категорию
add_action( 'wp_abilities_api_categories_init', 'my_plugin_register_category' );
function my_plugin_register_category() {
	wp_register_ability_category( 'site-information', [
		'label'       => 'Site Information',
		'description' => 'Abilities that provide information about the WordPress site.',
	] );
}

// Затем регистрируем абилити в этой категории
add_action( 'wp_abilities_api_init', 'my_plugin_register_ability' );
function my_plugin_register_ability() {
	wp_register_ability( 'my-plugin/site-info', [
		'category'            => 'site-information',
		'label'               => 'Site Info',
		'description'         => 'Returns information about this WordPress site',
		'execute_callback'    => 'my_plugin_get_siteinfo',
		'permission_callback' => fn ( $input ) => current_user_can( 'manage_options' ),
		'meta' => [
			'show_in_rest' => true,
		],
		'input_schema'  => [],
		'output_schema' => [
			'type'       => 'object',
			'properties' => [
				'site_name'         => [
					'type'        => 'string',
					'description' => 'The name of the WordPress site',
				],
				'site_url'          => [
					'type'        => 'string',
					'description' => 'The URL of the WordPress site',
				],
				'active_theme'      => [
					'type'        => 'string',
					'description' => 'The active theme of the WordPress site',
				],
				'active_plugins'    => [
					'type'        => 'array',
					'description' => 'List of active plugins on the WordPress site',
					'items'       => [
						'type' => 'string',
					],
				],
			],
		],
	] );
}

Подробнее: https://github.com/WordPress/abilities-api/blob/trunk/docs/php-api.md

PHP Функции и Хуки API

Функции

Управление abilities:

wp_register_ability() — регистрация новой ability
wp_unregister_ability() — удаление ability из реестра
wp_has_ability() — проверка, зарегистрирована ли ability
wp_get_ability() — получение зарегистрированной ability
wp_get_abilities() — получение всех зарегистрированных abilities

Управление категориями abilities:

wp_register_ability_category() — регистрация категории abilities
wp_unregister_ability_category() — удаление категории из реестра
wp_has_ability_category() — проверка, зарегистрирована ли категория
wp_get_ability_category() — получение зарегистрированной категории
wp_get_ability_categories() — получение всех категорий abilities

Хуки

Новые хуки для интеграции с Abilities API.

События:

wp_abilities_api_categories_init - вызывается при инициализации реестра категорий abilities (категории регистрируются здесь)
wp_abilities_api_init - вызывается при инициализации реестра abilities (abilities регистрируются здесь)
wp_before_execute_ability - вызывается перед выполнением ability
wp_after_execute_ability - вызывается после выполнения ability

Фильтры:

wp_register_ability_category_args - фильтрует аргументы категории abilities перед регистрацией
wp_register_ability_args - фильтрует аргументы ability перед регистрацией

Подробнее: https://github.com/WordPress/abilities-api/blob/trunk/docs/hooks.md

Naming Convention

Ability Name Convention

Рекомендуется придерживаться следующих правил именования abilities:

Использовать namespaced имена, чтобы избежать конфликтов, например my-plugin/my-ability.
Использовать только строчные латинские буквы, цифры, дефисы и слеши.
Использовать описательные, "действованные" имена, например process-payment`, `generate-report.
Общий формат: namespace/ability-name.

Category Slug Convention

wp_register_ability_category( string $slug, array $args )

Параметр $slug должен соответствовать следующим правилам:

Формат: может содержать только a-z, 0-9 (строчные буквенно-цифровые символы) и - (дефисы).
Корректные примеры: data-retrieval, ecommerce, site-information, user-management, category-123
Некорректные примеры:
- Прописные буквы: Data-Retrieval, MyCategory
- Подчёркивания: data_retrieval
- Специальные символы: data.retrieval, data/retrieval, data retrieval
- Дефис в начале/конце: -data, data-
- Двойные дефисы: data--retrieval

Проверка и получение abilities

Можно проверить наличие ability и получить ее программно (см. WP_Ability):

<?php
if ( wp_has_ability( 'my-plugin/get-post-count' ) ) {
	$ability = wp_get_ability( 'my-plugin/get-post-count' );

	echo $ability->get_label();
	echo $ability->get_description();
}

// получить все абилити
$all_abilities = wp_get_abilities();

foreach( $all_abilities as $ability ){
	echo $ability->get_name();
}

Обработка ошибок

Abilities должны корректно обрабатывать ошибки, возвращая объекты WP_Error:

<?php

function my_plugin_delete_post( $input ) {
	$post_id = $input['post_id'];

	if ( ! get_post( $post_id ) ) {
		return new WP_Error(
			'post_not_found',
			__( 'The specified post does not exist.', 'my-plugin' )
		);
	}

	$result = wp_delete_post( $post_id, true );

	if ( ! $result ) {
		return new WP_Error(
			'deletion_failed',
			__( 'Failed to delete the post.', 'my-plugin' )
		);
	}

	return array(
		'success' => true,
		'post_id' => $post_id,
	);
}

Валидация через JSON Schema (REST API)

Подробнее: https://github.com/WordPress/abilities-api/blob/trunk/docs/rest-api.md

Abilities API использует JSON Schema для валидации входных и выходных данных. Схемы выполняют две задачи:

Автоматическая проверка данных, передаваемых в abilities.
Самодокументируемые контракты API для разработчиков.

Определение схем является обязательным, если есть значения, которые необходимо передать или вернуть.

Использование REST API эндпоинтов

При включении Abilities API может автоматически публиковать зарегистрированные abilities через REST API в пространстве имен wp-abilities/v1:

GET /wp-abilities/v1/categories - список всех категорий abilities
GET /wp-abilities/v1/categories/{slug} - данные отдельной категории
GET /wp-abilities/v1/abilities - список всех abilities
GET /wp-abilities/v1/abilities/{name} - данные отдельной ability
GET|POST|DELETE /wp-abilities/v1/abilities/{name}/run - выполнение ability

Разработчики могут включить поддержку стандартных REST API эндпоинтов для abilities. Это делается через аргумент show_in_rest = true при регистрации ability.

wp_register_ability(
	'my-plugin/get-post-count',
	[
		'label' => __( 'Get Post Count', 'my-plugin' ),
		'description' => __( 'Retrieves the total number of published posts.', 'my-plugin' ),
		'category' => 'content-management',
		'input_schema' => [
			'type'        => 'string',
			'description' => __( 'The post type to count.', 'my-plugin' ),
			'default'     => 'post',
		],
		'output_schema' => [
			'type'        => 'integer',
			'description' => __( 'The number of published posts.', 'my-plugin' ),
		],
		'execute_callback' => 'my_plugin_get_post_count',
		'permission_callback' => fn() => current_user_can( 'read' ),
		'meta' => [
			'show_in_rest' => true,
		],
	]
);

Доступ ко всем REST эндпоинтам Abilities API требует аутентифицированного пользователя. Abilities API поддерживает все методы аутентификации WordPress REST API:

Cookie-аутентификация (same-origin запросы).
Application passwords (рекомендуется для внешнего доступа).
Кастомные плагины аутентификации.

После включения можно получать список, детали и выполнять abilities через REST API.

Список всех abilities:

curl -u 'USERNAME:APPLICATION_PASSWORD' \
  https://example.com/wp-json/wp-abilities/v1/abilities

Получить одну ability:

curl -u 'USERNAME:APPLICATION_PASSWORD' \
  https://example.com/wp-json/wp-abilities/v1/abilities/my-plugin/get-post-count

Выполнить ability:

curl -u 'USERNAME:APPLICATION_PASSWORD' \
  -X POST https://example.com/wp-json/wp-abilities/v1/abilities/my-plugin/get-post-count/run \
  -H "Content-Type: application/json" \
  -d '{"input": {"post_type": "page"}}'

API автоматически валидирует входные данные по схеме, проверяет права через permission_callback, выполняет ability, валидирует результат по output_schema и возвращает ответ в формате JSON.

Обратная совместимость

Abilities API - это новая возможность WordPress 6.9 и она не меняет существующую функциональность. Плагины и темы могут постепенно внедрять API без поломки текущего кода.

Разработчики, которые хотят поддерживать одновременно WordPress 6.9+ и более ранние версии, должны сначала проверять наличие функций API перед их использованием:

if ( function_exists( 'wp_register_ability' ) ) {
	add_action( 'wp_abilities_api_init', 'my_plugin_register_abilities' );
}

// или
if ( class_exists( 'WP_Ability' ) ) {
	add_action( 'wp_abilities_api_init', 'my_plugin_register_abilities' );
}

Дополнительные материалы

Sourse DOC: https://github.com/WordPress/abilities-api/tree/trunk/docs
GitHub Repo: https://github.com/WordPress/abilities-api/
Core Trac Ticket #64098
Abilities API Handbook
AI Building Blocks Initiative

Источник: https://make.wordpress.org/core/2025/11/10/abilities-api-in-wordpress-6-9/