wpseek.com
A WordPress-centric search engine for devs and theme authors
wp_register_ability › WordPress Function
Since6.9.0
Deprecatedn/a
› wp_register_ability ( $name, $args )
| Parameters: (2) |
|
| See: |
|
| Returns: |
|
| Defined at: |
|
| Codex: | |
| Change Log: |
|
Registers a new ability using the Abilities API. It requires three steps:
1. Hook into thewp_abilities_api_init action.
2. Call wp_register_ability() with a namespaced name and configuration.
3. Provide an execute_callback. For permission checks, set required_capabilities,
permission_callback, or both.
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,
),
'output_schema' => array(
'type' => 'string',
'enum' => array( 'positive', 'negative', 'neutral' ),
'description' => ( 'The sentiment result: positive, negative, or neutral.', 'my-plugin' ),
),
'execute_callback' => 'my_plugin_analyze_text',
'required_capabilities' => array( 'edit_posts' ),
'permission_callback' => 'my_plugin_can_analyze_text',
'meta' => array(
'annotations' => array(
'readonly' => true,
),
'public' => true,
),
)
);
}
add_action( 'wp_abilities_api_init', 'my_plugin_register_abilities' );
The text-processing category must be registered first with
wp_register_ability_category(), or the registration fails.
On failure, this function returns null and calls _doing_it_wrong() with the reason.
By default, the resulting notice is displayed when WP_DEBUG is enabled.
### Naming Conventions
Ability names must follow these rules:
- Include exactly one namespace and one ability name, separated by a single slash
(e.g., my-plugin/my-ability). Nested namespaces are not supported.
- Use only lowercase alphanumeric characters, dashes, and forward slashes.
- Use descriptive, action-oriented names (e.g., process-payment, generate-report).
### Categories
Every ability must specify a registered category. Categories group related abilities
so clients can discover and retrieve relevant subsets. Plugins can reuse an existing
category when appropriate, including categories registered by core. Custom categories must be
registered on wp_abilities_api_categories_init before abilities that reference them
are registered on wp_abilities_api_init:
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
An input schema is required when passing non-null input. Without one, only null
input is accepted and callbacks receive no arguments. When input is null, a
top-level default in the input schema is applied before validation.
An output schema is optional. When omitted, output schema validation is skipped.
Define one to document and validate the result returned by the ability:
'input_schema' => array(
'type' => 'string',
'description' => ( 'The text to be analyzed.', 'my-plugin' ),
'minLength' => 10,
),
'output_schema' => array(
'type' => 'string',
'enum' => array( 'positive', 'negative', 'neutral' ),
'description' => ( 'The sentiment result: positive, negative, or neutral.', 'my-plugin' ),
),
### Callbacks
#### Execute Callback
The execute callback performs the ability's core functionality. It receives
the input prepared by WP_Ability::prepare_input() when an input schema is
defined, and no arguments otherwise. It returns either a result or WP_Error
on failure. Exceptions thrown by execute or permission callbacks are caught
and converted to a WP_Error.
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 );
}
#### Required Capabilities and Permission Callback
Declare only the minimum capabilities required for every execution in
required_capabilities. Check additional capabilities that depend on the input
in permission_callback. Declaring capabilities needed only for particular inputs
can cause discovery to hide an ability the current user is allowed to execute
with other inputs.
Each required capability is checked with current_user_can() before the
permission callback runs. The callback is optional when the list is non-empty.
For an ability that everyone may execute, use `return_trueas the callback with no required capabilities. The permission callback determines whether the ability can be executed and must return a boolean orWP_Error. When called throughWP_Ability::execute(), it receives the same prepared input as the execute callback. Common use cases include checking user capabilities, validating API keys, or verifying system state. In the example above, every execution requiresedit_posts, and the callback only adds the check that depends on the input: function my_plugin_can_analyze_text( string $input ): bool|WP_Error { // Only administrators can analyze long texts. if ( mb_strlen( $input ) > 5000 ) { return current_user_can( 'manage_options' ); } return true; } ### Execution Lifecycle CallWP_Ability::execute()to prepare the input, check permissions, invoke the execute callback, and validate output. It returns the result or a WP_Erroron failure. Custom ability classes can override this behavior. Integrations that callWP_Ability::check_permissions()directly must pass it the input returned byWP_Ability::prepare_input(). Hooks run in this order, and processing stops at the first failure: 1.wp_ability_invokedaction, with the raw input. 2.wp_pre_execute_abilityfilter, which can short-circuit the rest of execution. 3.wp_ability_normalize_inputandwp_ability_validate_inputfilters, while the input is prepared. The input validation filter runs only when a non-empty input schema is defined. Sanitization has no filter. 4.wp_ability_permission_resultfilter. 5.wp_before_execute_abilityaction. 6.wp_ability_execute_resultandwp_ability_validate_outputfilters. 7.wp_after_execute_abilityaction. ### Client Exposure Exposure flags do not grant execution permission. Set the high-levelpublicflag to make an ability available to clients such as the REST API, MCP, or AI agents: 'meta' => array( 'public' => true, ), Thepublicflag seeds the default for each per-channel flag. For the REST API it seedsshow_in_rest`, which lets the ability be invoked via HTTP
requests. Set a per-channel flag directly to override that default. For
example, keep a public ability out of the REST API:
'meta' => array(
'public' => true,
'show_in_rest' => false,
),Related Functions: wp_unregister_ability, wp_register_ability_category, wp_register_core_abilities, wp_get_ability, wp_register_style
Source
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 );
}