wp_register_ability() │ WP 6.9.0

Registers a new ability using the Abilities API. It requires three steps:

1. Hook into the wp_abilities_api_init
2. Call wp_register_ability() a namespaced name and configuration.
3. Provide execute and permission callbacks.

Example:

function my_plugin_register_abilities(): void {
	wp_register_ability(
		'my-plugin/analyze-text',
		array(
			'label'               => __( 'Analyze Text', 'my-plugin' ),
			'description'         => __( 'Performs sentiment analysis on provided text.', 'my-plugin' ),
			'category'            => 'text-processing',
			'input_schema'        => array(
				'type'        => 'string',
				'description' => __( 'The text to be analyzed.', 'my-plugin' ),
				'minLength'   => 10,
				'required'    => true,
			),
			'output_schema'       => array(
				'type'        => 'string',
				'enum'        => array( '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'                => array(
				'annotations'   => array(
					'readonly' => true,
				),
				'show_in_rest' => true,
			),
		)
	);
}
add_action( 'wp_abilities_api_init', 'my_plugin_register_abilities' );

Naming Conventions

Ability names must follow these rules:

• Include a namespace prefix (e.g., my-plugin/my-ability).
• Use only lowercase alphanumeric characters, dashes, and forward slashes.
• Use descriptive, action-oriented names (e.g., process-payment, generate-report).

Categories

Abilities must be organized into categories. Ability categories provide better discoverability and must be registered before the abilities that reference them:

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

Input and Output Schemas

Schemas define the expected structure, type, and constraints for ability inputs and outputs using JSON Schema syntax. They serve two critical purposes: automatic validation of data passed to and returned from abilities, and self-documenting API contracts for developers.

WordPress implements a validator based on a subset of the JSON Schema Version 4 specification (https://json-schema.org/specification-links.html#draft-4). For details on supported JSON Schema properties and syntax, see the related WordPress REST API Schema documentation: https://developer.wordpress.org/rest-api/extending-the-rest-api/schema/#json-schema-basics

Defining schemas is mandatory when there is a value to pass or return. They ensure data integrity, improve developer experience, and enable better documentation:

'input_schema' => array(
	'type'        => 'string',
	'description' => __( 'The text to be analyzed.', 'my-plugin' ),
	'minLength'   => 10,
	'required'    => true,
),
'output_schema'       => array(
	'type'        => 'string',
	'enum'        => array( 'positive', 'negative', 'neutral' ),
	'description' => __( 'The sentiment result: positive, negative, or neutral.', 'my-plugin' ),
	'required'    => true,
),

Callbacks

Execute Callback

The execute callback performs the ability's core functionality. It receives optional input data and returns either a result or WP_Error on failure.

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 );
}

Permission Callback

The permission callback determines whether the ability can be executed. It receives the same input as the execute callback and must return a boolean or WP_Error. Common use cases include checking user capabilities, validating API keys, or verifying system state:

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

REST API Integration

Abilities can be exposed through the REST API by setting show_in_rest to true in the meta configuration:

'meta' => array(
	'show_in_rest' => true,
),

This allows abilities to be invoked via HTTP requests to the WordPress REST API.

Хуков нет.

Возвращает

WP_Ability|null. The registered ability instance on success, null on failure.

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

wp_register_ability( $name, $args ): ?WP_Ability;

$name(строка) (обязательный)

The name of the ability. Must be a namespaced string containing a prefix, e.g., my-plugin/my-ability. Can only contain lowercase alphanumeric characters, dashes, and forward slashes.

$args(массив) (обязательный)

.

Заметки

• Смотрите: WP_Abilities_Registry::register()
• Смотрите: wp_register_ability_category()
• Смотрите: wp_unregister_ability()

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

Код wp_register_ability() wp register ability ^{WP 6.9}

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 );
}