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( array $args = array() X-Ref

Retrieves registered abilities, optionally filtered by the given arguments.

When called without arguments, returns all registered abilities. When called
with an $args array, returns only abilities that match every specified condition.

Filtering pipeline (executed in order):

1. Declarative filters (`category`, `namespace`, `meta`) — per-item, AND logic between
arg types, OR logic within multi-value `category` arrays.
2. `item_include_callback` — per-item, caller-scoped. Return true to include, false to exclude.
3. `wp_get_abilities_item_include` filter — per-item, ecosystem-scoped. Plugins can enforce
universal inclusion rules regardless of what the caller passed.
4. `result_callback` — on the full matched array, caller-scoped. Sort, slice, or reshape.
5. `wp_get_abilities_result` filter — on the full array, ecosystem-scoped.

Steps 1–3 run inside a single loop over the registry — no extra iteration.

Examples:

// All abilities (unchanged behaviour).
$abilities = wp_get_abilities();

// Filter by category.
$abilities = wp_get_abilities( array( 'category' => 'content' ) );

// Filter by multiple categories (OR logic).
$abilities = wp_get_abilities( array( 'category' => array( 'content', 'settings' ) ) );

// Filter by namespace.
$abilities = wp_get_abilities( array( 'namespace' => 'woocommerce' ) );

// Filter by meta.
$abilities = wp_get_abilities( array( 'meta' => array( 'show_in_rest' => true ) ) );

// Combine filters (AND logic between arg types).
$abilities = wp_get_abilities( array(
'category' => 'content',
'namespace' => 'core',
'meta' => array( 'show_in_rest' => true ),
) );

// Caller-scoped per-item callback.
$abilities = wp_get_abilities( array(
'item_include_callback' => function ( WP_Ability $ability ) {
return current_user_can( 'manage_options' );
},
) );

// Caller-scoped result callback (sort + paginate).
$abilities = wp_get_abilities( array(
'result_callback' => function ( array $abilities ) {
usort( $abilities, fn( $a, $b ) => strcasecmp( $a->get_label(), $b->get_label() ) );
return array_slice( $abilities, 0, 10 );
},
) );

The pipeline always runs, even when called with no arguments. This ensures that the
`wp_get_abilities_item_include` and `wp_get_abilities_result` filters always fire,
giving plugins a reliable place to enforce universal inclusion or shaping rules.
For raw, unfiltered registry data that bypasses the filter pipeline entirely, use
{@see WP_Abilities_Registry::get_all_registered()} directly.

param: array $args {
return: WP_Ability[] An array of registered WP_Ability instances matching the given args,

_wp_get_abilities_match_meta( array $meta, array $conditions ) X-Ref

Checks whether an ability's meta array matches a set of required key/value conditions.

All conditions must match (AND logic). Supports nested arrays for structured meta,
e.g. `array( 'mcp' => array( 'public' => true ) )`.

param: array $meta The ability's meta array.
param: array $conditions The required key/value conditions to match against.
return: bool True if all conditions match, false otherwise.

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:	784 lines (32 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 11 functions