4.using-abilities.md

4. Using Abilities (wp_get_ability, wp_get_abilities)

Once abilities are registered, they can be retrieved and executed using global functions from the Abilities API.

Getting a Specific Ability (wp_get_ability)

To get a single ability object by its name (namespace/ability-name):

/**
 * Retrieves a registered ability using Abilities API.
 *
 * @param string $name The name of the registered ability, with its namespace.
 * @return ?WP_Ability The registered ability instance, or null if it is not registered.
 */
function wp_get_ability( string $name ): ?WP_Ability

// Example:
$site_info_ability = wp_get_ability( 'my-plugin/get-site-info' );

if ( $site_info_ability ) {
	// Ability exists and is registered
	$site_info = $site_info_ability->execute();
	if ( is_wp_error( $site_info ) ) {
		// Handle WP_Error
		echo 'Error: ' . $site_info->get_error_message();
	} else {
		// Use $site_info array
		echo 'Site Name: ' . $site_info['name'];
	}
} else {
	// Ability not found or not registered
}

Getting All Registered Abilities (wp_get_abilities)

wp_get_abilities() returns a WP_Abilities_Collection instance, which provides a fluent, chainable API for filtering and sorting:

/**
 * Retrieves a collection of registered abilities.
 *
 * Returns a WP_Abilities_Collection instance that provides a fluent, chainable
 * API for filtering, sorting, and manipulating abilities.
 *
 * @since n.e.x.t Returns WP_Abilities_Collection instead of array.
 * @return WP_Abilities_Collection Collection of WP_Ability instances.
 */
function wp_get_abilities(): WP_Abilities_Collection

// Example: Get all registered abilities
$abilities = wp_get_abilities();

// Iterate over the collection
foreach ( $abilities as $ability ) {
    echo 'Ability Name: ' . esc_html( $ability->get_name() ) . "\n";
    echo 'Label: ' . esc_html( $ability->get_label() ) . "\n";
    echo 'Description: ' . esc_html( $ability->get_description() ) . "\n";
    echo "---\n";
}

// Or convert to array if needed
$abilities_array = $abilities->to_array();

Filtering Abilities

The collection returned by wp_get_abilities() provides chainable methods for filtering and sorting. For detailed filtering documentation, see Advanced Filtering and Sorting.

Quick examples:

// Filter by category
$abilities = wp_get_abilities()->where_category( 'data-retrieval' );

// Search for abilities
$abilities = wp_get_abilities()->search( 'email' );

// Filter by namespace and meta
$abilities = wp_get_abilities()
    ->where_namespace( 'my-plugin' )
    ->where( 'meta.show_in_rest', true );

// Chain multiple filters
$abilities = wp_get_abilities()
    ->where_category( array( 'communication', 'data-retrieval' ) )
    ->where_namespace( 'my-plugin' )
    ->where( 'meta.show_in_rest', true )
    ->search( 'email' )
    ->sort_by( 'label' )
    ->all(); // Convert to array

// Get count without converting to array
$count = wp_get_abilities()
    ->where_category( 'math' )
    ->count();

See Advanced Filtering and Sorting for complete filtering documentation, including nested meta filters, comparison operators, and custom callbacks.

Executing an Ability ($ability->execute())

Once you have a WP_Ability object (usually from wp_get_ability), you execute it using the execute() method.

/**
 * Executes the ability after input validation and running a permission check.
 *
 * @param mixed $input Optional. The input data for the ability. Defaults to `null`.
 * @return mixed|WP_Error The result of the ability execution, or WP_Error on failure.
 */
// public function execute( $input = null )

// Example 1: Ability with no input parameters
$ability = wp_get_ability( 'my-plugin/get-site-info' );
if ( $ability ) {
    $site_info = $ability->execute(); // No input required
    if ( is_wp_error( $site_info ) ) {
        // Handle WP_Error
        echo 'Error: ' . $site_info->get_error_message();
    } else {
        // Use $site_info array
        echo 'Site Name: ' . $site_info['name'];
    }
}

// Example 2: Ability with input parameters
$ability = wp_get_ability( 'my-plugin/update-option' );
if ( $ability ) {
    $input = array(
        'option_name'  => 'blogname',
        'option_value' => 'My Updated Site Name',
    );

    $result = $ability->execute( $input );
    if ( is_wp_error( $result ) ) {
        // Handle WP_Error
        echo 'Error: ' . $result->get_error_message();
    } else {
        // Use $result
        if ( $result['success'] ) {
            echo 'Option updated successfully!';
            echo 'Previous value: ' . $result['previous_value'];
        }
    }
}

// Example 3: Ability with complex input validation
$ability = wp_get_ability( 'my-plugin/send-email' );
if ( $ability ) {
    $input = array(
        'to'      => 'user@example.com',
        'subject' => 'Hello from WordPress',
        'message' => 'This is a test message from the Abilities API.',
    );

    $result = $ability->execute( $input );
    if ( is_wp_error( $result ) ) {
        // Handle WP_Error
        echo 'Error: ' . $result->get_error_message();
    } elseif ( $result['sent'] ) {
        echo 'Email sent successfully!';
    } else {
        echo 'Email failed to send.';
    }
}

Checking Permissions ($ability->check_permissions())

You can check if the current user has permissions to execute the ability, also without executing it. The check_permissions() method returns either true, false, or a WP_Error object. true means permission is granted, false means the user simply lacks permission, and a WP_Error return value typically indicates a failure in the permission check process (such as an internal error or misconfiguration). You must use is_wp_error() to handle errors properly and distinguish between permission denial and actual errors:

$ability = wp_get_ability( 'my-plugin/update-option' );
if ( $ability ) {
    $input = array(
        'option_name'  => 'blogname',
        'option_value' => 'New Site Name',
    );

    // Check permission before execution - always use is_wp_error() first
    $has_permissions = $ability->check_permissions( $input );
    if ( true === $has_permissions ) {
        // Permissions granted – safe to execute.
        echo 'You have permissions to execute this ability.';
    } else {
        // Don't leak permission errors to unauthenticated users.
        if ( is_wp_error( $has_permissions ) ) {
            error_log( 'Permissions check failed: ' . $has_permissions->get_error_message() );
        }

        echo 'You do not have permissions to execute this ability.';
    }
}

Inspecting Ability Properties

The WP_Ability class provides several getter methods to inspect ability properties:

$ability = wp_get_ability( 'my-plugin/get-site-info' );
if ( $ability ) {
    // Basic properties
    echo 'Name: ' . $ability->get_name() . "\n";
    echo 'Label: ' . $ability->get_label() . "\n";
    echo 'Description: ' . $ability->get_description() . "\n";

    // Schema information
    $input_schema = $ability->get_input_schema();
    $output_schema = $ability->get_output_schema();

    echo 'Input Schema: ' . json_encode( $input_schema, JSON_PRETTY_PRINT ) . "\n";
    echo 'Output Schema: ' . json_encode( $output_schema, JSON_PRETTY_PRINT ) . "\n";

    // Metadata
    $meta = $ability->get_meta();
    if ( ! empty( $meta ) ) {
        echo 'Metadata: ' . json_encode( $meta, JSON_PRETTY_PRINT ) . "\n";
    }
}

Error Handling Patterns

The Abilities API uses several error handling mechanisms:

$ability = wp_get_ability( 'my-plugin/some-ability' );

if ( ! $ability ) {
    // Ability not registered
    echo 'Ability not found';
    return;
}

$result = $ability->execute( $input );

// Check for WP_Error (validation, permission, or callback errors)
if ( is_wp_error( $result ) ) {
    echo 'WP_Error: ' . $result->get_error_message();
    return;
}

// Check for null result (permission denied, invalid callback, or validation failure)
if ( is_null( $result ) ) {
    echo 'Execution returned null - check permissions and callback validity';
    return;
}

// Success - use the result
// Process $result based on the ability's output schema