PHPXRef 0.7.1 : WordPress Trunk (Updated Daily) : Detail view of abilities-api.php

Functions that are not part of a class:

wp_register_ability( string $name, array $args ) X-Ref

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

1. Hook into the `wp_abilities_api_init` action.
2. Call `wp_register_ability()` with 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.

return: WP_Ability|null The registered ability instance on success, `null` on failure.
param: string               $name The name of the ability. Must be a namespaced string containing
param: array<string, mixed> $args {

wp_unregister_ability( string $name ) X-Ref

Unregisters an ability from the Abilities API.

Removes a previously registered ability from the global registry. Use this to
disable abilities provided by other plugins or when an ability is no longer needed.

Can be called at any time after the ability has been registered.

Example:

if ( wp_has_ability( 'other-plugin/some-ability' ) ) {
wp_unregister_ability( 'other-plugin/some-ability' );
}

return: WP_Ability|null The unregistered ability instance on success, `null` on failure.
param: string $name The name of the ability to unregister, including namespace prefix

wp_has_ability( string $name ) X-Ref

Checks if an ability is registered.

Use this for conditional logic and feature detection before attempting to
retrieve or use an ability.

Example:

// Displays different UI based on available abilities.
if ( wp_has_ability( 'premium-plugin/advanced-export' ) ) {
echo 'Export with Premium Features';
} else {
echo 'Basic Export';
}

return: bool `true` if the ability is registered, `false` otherwise.
param: string $name The name of the ability to check, including namespace prefix

wp_get_ability( string $name ) X-Ref

Retrieves a registered ability.

Returns the ability instance for inspection or use. The instance provides access
to the ability's configuration, metadata, and execution methods.

Example:

// Prints information about a registered ability.
$ability = wp_get_ability( 'my-plugin/export-data' );
if ( $ability ) {
echo $ability->get_label() . ': ' . $ability->get_description();
}

return: WP_Ability|null The registered ability instance, or `null` if not registered.
param: string $name The name of the ability, including namespace prefix

wp_get_abilities() X-Ref

Retrieves all registered abilities.

Returns an array of all ability instances currently registered in the system.
Use this for discovery, debugging, or building administrative interfaces.

Example:

// Prints information about all available abilities.
$abilities = wp_get_abilities();
foreach ( $abilities as $ability ) {
echo $ability->get_label() . ': ' . $ability->get_description() . "\n";
}

return: WP_Ability[] An array of registered WP_Ability instances. Returns an empty

wp_register_ability_category( string $slug, array $args ) X-Ref

Registers a new ability category.

Ability categories provide a way to organize and group related abilities for better
discoverability and management. Ability categories must be registered before abilities
that reference them.

Ability categories must be registered on the `wp_abilities_api_categories_init` action hook.

Example:

function my_plugin_register_categories() {
wp_register_ability_category(
'content-management',
array(
'label' => __( 'Content Management', 'my-plugin' ),
'description' => __( 'Abilities for managing and organizing content.', 'my-plugin' ),
)
);
}
add_action( 'wp_abilities_api_categories_init', 'my_plugin_register_categories' );

return: WP_Ability_Category|null The registered ability category instance on success, `null` on failure.
param: string $slug The unique slug for the ability category. Must contain only lowercase
param: array<string, mixed> $args {

wp_unregister_ability_category( string $slug ) X-Ref

Unregisters an ability category.

Removes a previously registered ability category from the global registry. Use this to
disable ability categories that are no longer needed.

Can be called at any time after the ability category has been registered.

Example:

if ( wp_has_ability_category( 'deprecated-category' ) ) {
wp_unregister_ability_category( 'deprecated-category' );
}

return: WP_Ability_Category|null The unregistered ability category instance on success, `null` on failure.
param: string $slug The slug of the ability category to unregister.

wp_has_ability_category( string $slug ) X-Ref

Checks if an ability category is registered.

Use this for conditional logic and feature detection before attempting to
retrieve or use an ability category.

Example:

// Displays different UI based on available ability categories.
if ( wp_has_ability_category( 'premium-features' ) ) {
echo 'Premium Features Available';
} else {
echo 'Standard Features';
}

return: bool `true` if the ability category is registered, `false` otherwise.
param: string $slug The slug of the ability category to check.

wp_get_ability_category( string $slug ) X-Ref

Retrieves a registered ability category.

Returns the ability category instance for inspection or use. The instance provides access
to the ability category's configuration and metadata.

Example:

// Prints information about a registered ability category.
$ability_category = wp_get_ability_category( 'content-management' );
if ( $ability_category ) {
echo $ability_category->get_label() . ': ' . $ability_category->get_description();
}

return: WP_Ability_Category|null The ability category instance, or `null` if not registered.
param: string $slug The slug of the ability category.

wp_get_ability_categories() X-Ref

Retrieves all registered ability categories.

Returns an array of all ability category instances currently registered in the system.
Use this for discovery, debugging, or building administrative interfaces.

Example:

// Prints information about all available ability categories.
$ability_categories = wp_get_ability_categories();
foreach ( $ability_categories as $ability_category ) {
echo $ability_category->get_label() . ': ' . $ability_category->get_description() . "\n";
}

return: WP_Ability_Category[] An array of registered ability category instances. Returns an empty array

File Size:	614 lines (24 kb)
Included or required:	0 times
Referenced:	0 times
Includes or requires:	0 files

PHP Cross Reference of WordPress Trunk (Updated Daily)

/wp-includes/ -> abilities-api.php (summary)

Defines 10 functions