# wp_register_ability()

URL: https://chugunov.pro/api-wordpress/functions/wp_register_ability/
Проверено на WordPress 6.9, обновлено 06.08.2026.
Источник: независимый русскоязычный справочник chugunov.pro. Не является официальной документацией WordPress.

Тип: функция.
Появился в версии: 6.9.0.

## Сигнатура

```php
wp_register_ability( string $name, $args ): WP_Ability|null
```

## Описание

- Hook into the `wp_abilities_api_init` action.

- Call `wp_register_ability()` with a namespaced name and configuration.

- 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](#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](#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](#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](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](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](#callbacks)[Execute Callback](#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](#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](#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.[See also](#see-also)
- [WP_Abilities_Registry::register()](https://developer.wordpress.org/reference/classes/WP_Abilities_Registry/register/)

- [wp_register_ability_category()](https://developer.wordpress.org/reference/functions/wp_register_ability_category/)

- [wp_unregister_ability()](https://developer.wordpress.org/reference/functions/wp_unregister_ability/)

## Параметры

- `$name` `string` — обязательный. Имя способности. Должно быть строкой с пространством имён, содержащей префикс, например my-plugin/my-ability. Может содержать только строчные буквенно-цифровые символы, дефисы и прямые слеши.

## Возвращаемое значение

`WP_Ability|null` — null

## Исходный код

Файл: `wp-includes/abilities-api.php:278`

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

## История изменений

- 6.9.0 — Introduced.

## Связанные

Использует: `WP_Abilities_Registry::get_instance`, [`doing_action`](https://chugunov.pro/api-wordpress/functions/doing_action/), [`__`](https://chugunov.pro/api-wordpress/functions/__/), [`esc_html`](https://chugunov.pro/api-wordpress/functions/esc_html/), [`_doing_it_wrong`](https://chugunov.pro/api-wordpress/functions/_doing_it_wrong/).
Используется в: [`wp_register_core_abilities`](https://chugunov.pro/api-wordpress/functions/wp_register_core_abilities/).

Оригинал в официальной документации: https://developer.wordpress.org/reference/functions/wp_register_ability/