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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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