6. Hooks

The Abilities API provides WordPress Action and Filter Hooks that allow developers to monitor and respond to ability execution events.

Quick Links

Actions
- before_execute_ability
- after_execute_ability
Filters
- register_ability_args

Actions

`before_execute_ability`

Fires immediately before an ability gets executed, after permission checks have passed but before the execution callback is called.

do_action( 'before_execute_ability', $ability_name, $input );

Parameters

$ability_name (string): The namespaced name of the ability being executed (e.g., my-plugin/get-posts).
$input (mixed): The input data passed to the ability.

Usage Example

/**
 * Log each ability execution attempt.
 * @param string $ability_name The name of the ability being executed.
 * @param mixed  $input        The input data passed to the ability.
 */
function log_ability_execution( string $ability_name, $input ) {
    error_log( 'About to execute ability: ' . $ability_name );
    if ( $input !== null ) {
        error_log( 'Input: ' . wp_json_encode( $input ) );
    }
}
add_action( 'before_execute_ability', 'log_ability_execution', 10, 2 );

`after_execute_ability`

Fires immediately after an ability has finished executing successfully, after output validation has passed.

do_action( 'after_execute_ability', string $ability_name, $input, $result );

Parameters

$ability_name (string): The namespaced name of the ability that was executed.
$input (mixed): The input data that was passed to the ability.
$result (mixed): The validated result returned by the ability's execution callback.

Usage Example

/**
 * Log the result of each ability execution.
 *
 * @param string $ability_name The name of the executed ability.
 * @param mixed  $input        The input data passed to the ability.
 * @param mixed  $result       The result returned by the ability.
 */
function log_ability_result( string $ability_name, $input, $result ) {
    error_log( 'Completed ability: ' . $ability_name );
    error_log( 'Result: ' . wp_json_encode( $result ) );
}
add_action( 'after_execute_ability', 'log_ability_result', 10, 3 );

Filters

`register_ability_args`

Allows modification of an Ability's args before they are validated and used to instantiate the Ability.

$args = apply_filters( 'register_ability_args', array $args, string $ability_name );

Parameters

$args (array<string,mixed>): The arguments used to instantiate the ability. See wp_register_ability() for the full list of args.
$ability_name (string): The namespaced name of the ability being registered (e.g., my-plugin/get-posts).

Usage Example

/**
 * Modify ability args before validation.
 *
 * @param array<string,mixed> $args         The arguments used to instantiate the ability.
 * @param string              $ability_name The name of the ability, with its namespace.
 *
 * @return array<string,mixed> The modified ability arguments.
 */
function my_modify_ability_args( array $args, string $ability_name ): array {
    // Check if the ability name matches what you're looking for.
    if ( 'my-namespace/my-ability' !== $ability_name ) {
      return $args;
    }

    // Modify the args as needed.
    $args['label'] = __('My Custom Ability Label');

    // You can use the old args to build new ones.
    $args['description'] = sprintf(
        /* translators: 1: Ability name 2: Previous description */
        __('This is a custom description for the ability %s. Previously the description was %s', 'text-domain'),
        $ability_name,
        $args['description'] ?? 'N/A'
    );

    // Even if they're callbacks.
    $args['permission_callback' ] = static function ( $input = null ) use ( $args, $ability_name ) {
        $previous_check = is_callable( $args['permission_callback'] ) ? $args['permission_callback']( $input ) : true;

        // If we already failed, no need for stricter checks.
        if ( ! $previous_check || is_wp_error( $previous_check ) ) {
            return $previous_check;
        }

        return current_user_can( 'my_custom_ability_cap', $ability_name );
    }

    return $args;
}
add_filter( 'register_ability_args', 'my_modify_ability_args', 10, 2 );

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!