{"id":159634,"date":"2025-12-03T06:56:33","date_gmt":"2025-12-03T06:56:33","guid":{"rendered":"https:\/\/developer.wordpress.org\/?post_type=apis-handbook&#038;p=159634"},"modified":"2025-12-03T06:56:33","modified_gmt":"2025-12-03T06:56:33","slug":"getting-started","status":"publish","type":"apis-handbook","link":"https:\/\/developer.wordpress.org\/apis\/abilities-api\/getting-started\/","title":{"rendered":"Getting started"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">The Abilities API was added to WordPress in <a href=\"https:\/\/core.trac.wordpress.org\/ticket\/64098\">version 6.9<\/a>. <\/p>\n\n\n\n<p class=\"wp-block-paragraph\">For backwards compatibility, you can check if the <code>WP_Ability<\/code> class is available. <\/p>\n\n\n\n<pre class=\"wp-block-code\"><code lang=\"php\" class=\"language-php\">if ( ! class_exists( 'WP_Ability' ) ) {\n\t\/\/ E.g. add an admin notice about the missing dependency.\n\tadd_action(\n\t\t'admin_notices',\n\t\tstatic function () {\n\t\t\twp_admin_notice(\n\t\t\t\tesc_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' ),\n\t\t\t\t'error'\n\t\t\t);\n\t\t}\n\t);\n\n\treturn;\n}<\/code><\/pre>\n\n\n\n<h2 class=\"wp-block-heading\">Basic Usage Example<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">The below example is for a plugin implementation, but it could also be adapted for a theme&#8217;s <code>functions.php<\/code><\/p>\n\n\n\n<pre class=\"wp-block-code\"><code class=\"\">&lt;?php\n\/\/ 1. Register the ability when the Abilities API is initialized.\n\/\/ Using `wp_abilities_api_init` ensures the API is fully loaded.\nadd_action( 'wp_abilities_api_init', 'wporg_register_abilities' );\n\/**\n * Register custom abilities.\n *\n * @return void\n *\/\nfunction wporg_register_abilities() {\n\twp_register_ability(\n\t\t'wporg\/get-site-title',\n\t\tarray(\n\t\t\t'label'               =&gt; __( 'Get Site Title', 'textdomain' ),\n\t\t\t'description'         =&gt; __( 'Retrieves the title of the current WordPress site.', 'textdomain' ),\n\t\t\t'output_schema'       =&gt; array(\n\t\t\t\t'type'        =&gt; 'string',\n\t\t\t\t'description' =&gt; 'The site title.',\n\t\t\t),\n\t\t\t'execute_callback'    =&gt; 'wporg_get_site_title',\n\t\t\t'permission_callback' =&gt; '__return_true', \/\/ Everyone can access this.\n\t\t\t'meta'                =&gt; array(\n\t\t\t\t'category'     =&gt; 'site-info',\n\t\t\t\t'show_in_rest' =&gt; true, \/\/ Optional: expose via REST API.\n\t\t\t),\n\t\t)\n\t);\n}\n\/\/ 2. Define a callback function for your ability.\n\/**\n * Callback to get the site title.\n *\n * @return string\n *\/\nfunction wporg_get_site_title(): string {\n\treturn get_bloginfo( 'name' );\n}\n\n\n\/\/ 3. Later, you can retrieve and execute the ability.\nadd_action( 'admin_init', 'wporg_use_ability' );\n\/**\n * Use the registered ability.\n *\n * @return void\n *\/\nfunction wporg_use_ability() {\n\t$ability = wp_get_ability( 'wporg\/get-site-title' );\n\tif ( ! $ability ) {\n\t\t\/\/ Ability not found.\n\t\treturn;\n\t}\n\n\t$site_title = $ability-&gt;execute();\n\tif ( is_wp_error( $site_title ) ) {\n\t\t\/\/ Handle execution error.\n\t\terror_log( 'Execution error: ' . $site_title-&gt;get_error_message() );\n\t\treturn;\n\t}\n\n\t\/\/ `$site_title` now holds the result of `get_bloginfo( 'name' )`.\n\techo 'Site Title: ' . esc_html( $site_title );\n}<\/code><\/pre>\n","protected":false},"author":7511363,"featured_media":0,"parent":159632,"menu_order":0,"template":"","meta":{"_crdt_document":"","footnotes":""},"class_list":["post-159634","apis-handbook","type-apis-handbook","status-publish","hentry","type-handbook"],"revision_note":"","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/apis-handbook\/159634","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/apis-handbook"}],"about":[{"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/types\/apis-handbook"}],"author":[{"embeddable":true,"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/users\/7511363"}],"version-history":[{"count":3,"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/apis-handbook\/159634\/revisions"}],"predecessor-version":[{"id":159745,"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/apis-handbook\/159634\/revisions\/159745"}],"up":[{"embeddable":true,"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/apis-handbook\/159632"}],"wp:attachment":[{"href":"https:\/\/developer.wordpress.org\/wp-json\/wp\/v2\/media?parent=159634"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}