WordPress ability core functions

• wp_register_ability( string $name, array $args ) to register a new ability
• wp_register_ability_category( string $slug, array $args ) to register a new ability category

Always check if the function exists before calling it, to ensure compatibility with WordPress versions prior to 6.9:

if ( ! function_exists( 'wp_register_ability' ) ) {
    return;
}

Adding a new ability

To add a new ability, follow these steps:

• One ability = one class implementing AbilitiesInterface
• Place the class adjacent to the feature it belongs to
• Register the ability class in the feature's ServiceProvider
• Register the ability in the related subscriber, using the wp_abilities_api_init hook

An ability name must be unique and follow the format wp-rocket/ability-name, where wp-rocket is the vendor name and ability-name is a descriptive name for the ability. Use hyphens to separate words in the ability name.

The check_permissions()method should always verify against the current user capabilities, using current_user_can( 'rocket_manage_options ) by default, to ensure that only authorized users can execute the ability, except explicitly required otherwise.

An ability must be associated to an ability category. If the category doesn't exist yet, register a new one in the related subscriber using the wp_abilities_api_categories_init hook.

Make the ability available to the REST API and the MCP by adding meta.show_in_rest=true and meta.mcp.public=true when registering the ability, unless explicitly required otherwise.

Annotations should be added to the meta field when registering the ability, as an array of key-value pairs:

• readonly: true or false, to indicate if the ability doesn't modify data
• destructive: true or false, to indicate if the ability may delete/destroy data
• idempotent: true or false, to indicate Same input → same output

An example of an ability class can be found in the /inc/Engine/Abilities/Options/GetOptions.php file.

Input and Output Schema

If an ability requires input parameters, the parameters of the execute() method should always match the input schema defined when registering the ability.

The return value of the execute() method of an ability should always match the output schema defined when registering the ability.

Testing

Unit tests

Test only the execute() method of the ability class, which contains the logic to perform the action associated with the ability. Mock any dependencies and assert that the method behaves as expected under different conditions.

An example of unit tests for an ability class can be found in the /tests/Unit/inc/Engine/Abilities/Options/GetOptions/ExecuteTest.php file.

Integration tests

Check for WordPress version compatibility, abilities are available starting WordPress 6.9. Mark skip test if version under test is lower than 6.9.

Set up user to ensure ability permissions are correctly applied. Add scenario where user has the ability and another where they don't, and assert that the expected outcomes occur in both cases.

Test ability execution output by getting the ability WP_Ability object using wp_get_ability( $ability_name ) and calling the execute() method. Assert that the output is correct based on the input parameters and the expected behavior of the ability.

An example of integration tests for an ability class can be found in the /tests/Integration/inc/Engine/Abilities/Options/GetOptions/RegisterGetOptionsAbilityTest.php file.