Merge branch 'trunk' into update/version-0.2.0-preps

Author: gziolo

docs/1.intro.md

@@ -1,12 +1,12 @@
 # 1. Introduction & Overview
 
-**What is the Abilities API?**
+## What is the Abilities API?
 
 The WordPress Abilities API provides a standardized way to register and discover distinct units of functionality within a WordPress site. These units, called "Abilities", represent specific actions or capabilities that components can perform, with clearly defined inputs, outputs, and permissions.
 
 It acts as a central registry, making it easier for different parts of WordPress, third-party plugins, themes, and external systems (like AI agents) to understand and interact with the capabilities available on a specific site.
 
-**Core Concepts**
+## Core Concepts
 
 - **Ability:** A distinct piece of functionality with a unique name following the `namespace/ability-name` pattern. Each ability has a human-readable name and description, input/output definitions (using JSON Schema), optional permissions, and an associated callback function for execution. Each registered Ability is an instance of the `WP_Ability` class.
 - **Registry:** A central, singleton object (`WP_Abilities_Registry`) that holds all registered abilities. It provides methods for registering, unregistering, finding, and querying abilities.
@@ -15,7 +15,7 @@ It acts as a central registry, making it easier for different parts of WordPress
 - **Permission Callback:** An optional function that determines if the current user can execute a specific ability. 
 - **Namespace:** The first part of an ability name (before the slash), typically matching the plugin or component name that registers the ability.
 
-**Goals and Benefits**
+## Goals and Benefits
 
 - **Standardization:** Provides a single, consistent way to expose site capabilities.
 - **Discoverability:** Makes functionality easily discoverable by AI systems and automation tools.
@@ -24,15 +24,15 @@ It acts as a central registry, making it easier for different parts of WordPress
 - **Extensibility:** Simple registration pattern allows any plugin or theme to expose their capabilities.
 - **AI-Friendly:** Machine-readable format enables intelligent automation and AI agent interactions.
 
-**Use Cases**
+## Use Cases
 
 - **AI Integration:** Allow AI agents to discover and interact with site capabilities.
 - **Plugin Interoperability:** Enable plugins to discover and use each other's functionality.
 - **Automation Tools:** Provide programmatic access to site features.
 - **API Documentation:** Self-documenting capabilities with schema validation.
 - **Developer Tools:** Standardized way to expose plugin functionality.
 
-**Registration Example**
+## Registration Example
 
 ```php
 add_action( 'abilities_api_init', 'my_plugin_register_ability');

docs/2.getting-started.md

@@ -22,9 +22,9 @@ wp plugin install https://github.com/WordPress/abilities-api/releases/latest/dow
   "$schema": "https://schemas.wp.org/trunk/wp-env.json",
   // ... other config ...
   "plugins": [
-    "WordPress/abilities-api",
+    "WordPress/abilities-api"
     // ... other plugins ...
-  ],
+  ]
   // ... more config ...
 }
 ```
@@ -97,13 +97,13 @@ The below example is for a plugin implementation, but it could also be adapted f
 ```php
 <?php
 
-// 1. Define a callback function for your ability
+// 1. Define a callback function for your ability.
 function my_plugin_get_site_title( array $input = array() ): string {
     return get_bloginfo( 'name' );
 }
 
-// 2. Register the ability when the Abilities API is initialized
-// Using abilities_api_init ensures the API is fully loaded
+// 2. Register the ability when the Abilities API is initialized.
+// Using `abilities_api_init` ensures the API is fully loaded.
 add_action( 'abilities_api_init', 'my_plugin_register_abilities' );
 
 function my_plugin_register_abilities() {
@@ -127,16 +127,24 @@ function my_plugin_register_abilities() {
     ) );
 }
 
-// 3. Later, you can retrieve and execute the ability
+// 3. Later, you can retrieve and execute the ability.
 add_action( 'admin_init', 'my_plugin_use_ability' );
 
 function my_plugin_use_ability() {
     $ability = wp_get_ability( 'my-plugin/get-site-title' );
+    if ( ! $ability ) {
+        // Ability not found.
+        return;
+    }
 
-    if ( $ability && $ability->has_permission() ) {
-        $site_title = $ability->execute();
-        // $site_title now holds the result of get_bloginfo('name')
-        // error_log( 'Site Title: ' . $site_title );
+    $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 );
 }
 ```

docs/3.registering-abilities.md

@@ -1,8 +1,8 @@
-### 3. Registering Abilities (`wp_register_ability`)
+# 3. Registering Abilities (`wp_register_ability`)
 
 The primary way to add functionality to the Abilities API is by using the `wp_register_ability()` function, typically hooked into the `abilities_api_init` action.
 
-**Function Signature**
+## Function Signature
 
 ```php
 wp_register_ability( string $id, array $args ): ?\WP_Ability
@@ -12,7 +12,7 @@ wp_register_ability( string $id, array $args ): ?\WP_Ability
 - `$args` (`array`): An array of arguments defining the ability configuration.
 - **Return:** (`?\WP_Ability`) An instance of the registered ability if it was successfully registered, `null` on failure (e.g., invalid arguments, duplicate ID).
 
-**Parameters Explained**
+## Parameters Explained
 
 The `$args` array accepts the following keys:
 
@@ -29,17 +29,17 @@ The `$args` array accepts the following keys:
   - If the input does not validate against the input schema, the permission callback will not be called, and a `WP_Error` will be returned instead.
 - `meta` (`array`, **Optional**): An associative array for storing arbitrary additional metadata about the ability.
 
-**Ability ID Convention**
+## Ability ID Convention
 
 The `$id` parameter must follow the pattern `namespace/ability-name`:
 
 - **Format:** Must contain only lowercase alphanumeric characters (`a-z`, `0-9`), hyphens (`-`), and one forward slash (`/`) for namespacing.
 - **Convention:** Use your plugin slug as the namespace, like `my-plugin/ability-name`.
 - **Examples:** `my-plugin/update-settings`, `woocommerce/get-product`, `contact-form/send-message`, `analytics/track-event`
 
-**Code Examples**
+## Code Examples
 
-**1. Registering a Simple Data Retrieval Ability**
+### Registering a Simple Data Retrieval Ability
 
 ```php
 add_action( 'abilities_api_init', 'my_plugin_register_site_info_ability' );
@@ -82,7 +82,7 @@ function my_plugin_register_site_info_ability() {
 }
 ```
 
-**2. Registering an Ability with Input Parameters**
+### Registering an Ability with Input Parameters
 
 ```php
 add_action( 'abilities_api_init', 'my_plugin_register_update_option_ability' );
@@ -136,7 +136,7 @@ function my_plugin_register_update_option_ability() {
 }
 ```
 
-**3. Registering an Ability with Plugin Dependencies**
+### Registering an Ability with Plugin Dependencies
 
 ```php
 add_action( 'abilities_api_init', 'my_plugin_register_woo_stats_ability' );
@@ -194,7 +194,7 @@ function my_plugin_register_woo_stats_ability() {
 }
 ```
 
-**4. Registering an Ability That May Fail**
+### Registering an Ability That May Fail
 
 ```php
 add_action( 'abilities_api_init', 'my_plugin_register_send_email_ability' );

docs/4.using-abilities.md

@@ -1,8 +1,8 @@
-### 4. Using Abilities (`wp_get_ability`, `wp_get_abilities`)
+# 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`)**
+## Getting a Specific Ability (`wp_get_ability`)
 
 To get a single ability object by its name (namespace/ability-name):
 
@@ -20,7 +20,7 @@ $site_info_ability = wp_get_ability( 'my-plugin/get-site-info' );
 
 if ( $site_info_ability ) {
 	// Ability exists and is registered
-	$result = $site_info_ability->execute();
+	$site_info = $site_info_ability->execute();
 	if ( is_wp_error( $site_info ) ) {
 		// Handle WP_Error
 		echo 'Error: ' . $site_info->get_error_message();
@@ -33,7 +33,7 @@ if ( $site_info_ability ) {
 }
 ```
 
-**Getting All Registered Abilities (`wp_get_abilities`)**
+## Getting All Registered Abilities (`wp_get_abilities`)
 
 To get an array of all registered abilities:
 
@@ -56,7 +56,7 @@ foreach ( $all_abilities as $name => $ability ) {
 }
 ```
 
-**Executing an Ability (`$ability->execute()`)**
+## Executing an Ability (`$ability->execute()`)
 
 Once you have a `WP_Ability` object (usually from `wp_get_ability`), you execute it using the `execute()` method.
 
@@ -124,9 +124,9 @@ if ( $ability ) {
 }
 ```
 
-**Checking Permissions (`$ability->has_permission()`)**
+## Checking Permissions (`$ability->check_permissions()`)
 
-Before executing an ability, you can check if the current user has permission:
+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:
 
 ```php
 $ability = wp_get_ability( 'my-plugin/update-option' );
@@ -136,26 +136,23 @@ if ( $ability ) {
         'option_value' => 'New Site Name',
     );
 
-    // Check permission before execution
-    if ( $ability->has_permission( $input ) ) {
-        $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'];
-			}
-        }
+    // 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 {
-        echo 'You do not have permission to execute this ability.';
+        // 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**
+## Inspecting Ability Properties
 
 The `WP_Ability` class provides several getter methods to inspect ability properties:
 
@@ -182,7 +179,7 @@ if ( $ability ) {
 }
 ```
 
-**Error Handling Patterns**
+## Error Handling Patterns
 
 The Abilities API uses several error handling mechanisms:
 

includes/abilities-api/class-wp-ability.php

@@ -312,12 +312,12 @@ protected function validate_input( $input = null ) {
 	 *
 	 * The input is validated against the input schema before it is passed to to permission callback.
 	 *
-	 * @since 0.1.0
+	 * @since N.E.X.T
 	 *
 	 * @param mixed $input Optional. The input data for permission checking. Default `null`.
 	 * @return bool|\WP_Error Whether the ability has the necessary permission.
 	 */
-	public function has_permission( $input = null ) {
+	public function check_permissions( $input = null ) {
 		$is_valid = $this->validate_input( $input );
 		if ( is_wp_error( $is_valid ) ) {
 			return $is_valid;
@@ -330,6 +330,24 @@ public function has_permission( $input = null ) {
 		return call_user_func( $this->permission_callback, $input );
 	}
 
+	/**
+	 * Checks whether the ability has the necessary permissions (deprecated).
+	 *
+	 * The input is validated against the input schema before it is passed to to permission callback.
+	 *
+	 * @deprecated N.E.X.T Use check_permissions() instead.
+	 * @see WP_Ability::check_permissions()
+	 *
+	 * @since 0.1.0
+	 *
+	 * @param mixed $input Optional. The input data for permission checking. Default `null`.
+	 * @return bool|\WP_Error Whether the ability has the necessary permission.
+	 */
+	public function has_permission( $input = null ) {
+		_deprecated_function( __METHOD__, 'N.E.X.T', 'WP_Ability::check_permissions()' );
+		return $this->check_permissions( $input );
+	}
+
 	/**
 	 * Executes the ability callback.
 	 *
@@ -394,7 +412,7 @@ protected function validate_output( $output ) {
 	 * @return mixed|\WP_Error The result of the ability execution, or WP_Error on failure.
 	 */
 	public function execute( $input = null ) {
-		$has_permissions = $this->has_permission( $input );
+		$has_permissions = $this->check_permissions( $input );
 		if ( true !== $has_permissions ) {
 			if ( is_wp_error( $has_permissions ) ) {
 				if ( 'ability_invalid_input' === $has_permissions->get_error_code() ) {

includes/rest-api/endpoints/class-wp-rest-abilities-run-controller.php

@@ -163,7 +163,7 @@ public function run_ability_permissions_check( $request ) {
 		}
 
 		$input = $this->get_input_from_request( $request );
-		if ( ! $ability->has_permission( $input ) ) {
+		if ( ! $ability->check_permissions( $input ) ) {
 			return new \WP_Error(
 				'rest_ability_cannot_execute',
 				__( 'Sorry, you are not allowed to execute this ability.' ),

tests/unit/abilities-api/wpRegisterAbility.php

@@ -134,7 +134,7 @@ public function test_register_valid_ability(): void {
 		$this->assertSame( self::$test_ability_args['output_schema'], $result->get_output_schema() );
 		$this->assertSame( self::$test_ability_args['meta'], $result->get_meta() );
 		$this->assertTrue(
-			$result->has_permission(
+			$result->check_permissions(
 				array(
 					'a' => 2,
 					'b' => 3,
@@ -164,7 +164,7 @@ public function test_register_ability_no_permissions(): void {
 		$result = wp_register_ability( self::$test_ability_name, self::$test_ability_args );
 
 		$this->assertFalse(
-			$result->has_permission(
+			$result->check_permissions(
 				array(
 					'a' => 2,
 					'b' => 3,
@@ -289,7 +289,7 @@ public function test_permission_callback_no_input_schema_match(): void {
 
 		$result = wp_register_ability( self::$test_ability_name, self::$test_ability_args );
 
-		$actual = $result->has_permission(
+		$actual = $result->check_permissions(
 			array(
 				'a'       => 2,
 				'b'       => 3,
@@ -308,6 +308,27 @@ public function test_permission_callback_no_input_schema_match(): void {
 		);
 	}
 
+	/**
+	 * Tests that deprecated has_permission() method still works.
+	 *
+	 * @expectedDeprecated WP_Ability::has_permission
+	 */
+	public function test_has_permission_deprecated_coverage(): void {
+		do_action( 'abilities_api_init' );
+
+		$result = wp_register_ability( self::$test_ability_name, self::$test_ability_args );
+
+		// Test that deprecated method still works
+		$this->assertTrue(
+			$result->has_permission(
+				array(
+					'a' => 2,
+					'b' => 3,
+				)
+			)
+		);
+	}
+
 	/**
 	 * Tests permission callback receiving input for contextual permission checks.
 	 */
@@ -325,7 +346,7 @@ public function test_permission_callback_receives_input(): void {
 
 		// Test with a > b (should be allowed)
 		$this->assertTrue(
-			$result->has_permission(
+			$result->check_permissions(
 				array(
 					'a' => 5,
 					'b' => 3,
@@ -342,7 +363,7 @@ public function test_permission_callback_receives_input(): void {
 
 		// Test with a < b (should be denied)
 		$this->assertFalse(
-			$result->has_permission(
+			$result->check_permissions(
 				array(
 					'a' => 2,
 					'b' => 8,