Getting started

The Abilities API was added to WordPress in version 6.9.

For backwards compatibility, you can check if the WP_Ability class is available.

if ( ! class_exists( 'WP_Ability' ) ) {
	// E.g. add an admin notice about the missing dependency.
	add_action(
		'admin_notices',
		static function () {
			wp_admin_notice(
				esc_html__( 'This plugin requires the Abilities API, which is only available in WordPress 6.9 or newer. Please update your WordPress version to use this plugin.', 'textdomain' ),
				'error'
			);
		}
	);

	return;
}

Basic Usage Example

The below example is for a plugin implementation, but it could also be adapted for a theme’s functions.php

<?php
// 1. Register the ability when the Abilities API is initialized.
// Using `wp_abilities_api_init` ensures the API is fully loaded.
add_action( 'wp_abilities_api_init', 'wporg_register_abilities' );
/**
 * Register custom abilities.
 *
 * @return void
 */
function wporg_register_abilities() {
	wp_register_ability(
		'wporg/get-site-title',
		array(
			'label'               => __( 'Get Site Title', 'textdomain' ),
			'description'         => __( 'Retrieves the title of the current WordPress site.', 'textdomain' ),
			'output_schema'       => array(
				'type'        => 'string',
				'description' => 'The site title.',
			),
			'execute_callback'    => 'wporg_get_site_title',
			'permission_callback' => '__return_true', // Everyone can access this.
			'meta'                => array(
				'category'     => 'site-info',
				'show_in_rest' => true, // Optional: expose via REST API.
			),
		)
	);
}
// 2. Define a callback function for your ability.
/**
 * Callback to get the site title.
 *
 * @return string
 */
function wporg_get_site_title(): string {
	return get_bloginfo( 'name' );
}


// 3. Later, you can retrieve and execute the ability.
add_action( 'admin_init', 'wporg_use_ability' );
/**
 * Use the registered ability.
 *
 * @return void
 */
function wporg_use_ability() {
	$ability = wp_get_ability( 'wporg/get-site-title' );
	if ( ! $ability ) {
		// Ability not found.
		return;
	}

	$site_title = $ability->execute();
	if ( is_wp_error( $site_title ) ) {
		// Handle execution error.
		error_log( 'Execution error: ' . $site_title->get_error_message() );
		return;
	}

	// `$site_title` now holds the result of `get_bloginfo( 'name' )`.
	echo 'Site Title: ' . esc_html( $site_title );
}