feat!: make permission_callback arg required

docs/3.registering-abilities.md

@@ -23,10 +23,10 @@ The `$args` array accepts the following keys:
 - `execute_callback` (`callable`, **Required**): The PHP function or method to execute when this ability is called.
  - The callback receives one optional argument: it can have any type as defined in the input schema (e.g., `array`, `object`, `string`, etc.).
  - The callback should return the result of the ability's operation or return a `WP_Error` object on failure.
-- `permission_callback` (`callable`|`null`, **Optional**): A callback function to check if the current user has permission to execute this ability.
- - Should return `true` if the user has permission, or a `WP_Error` object otherwise.
- - If not provided, the ability will only validate input parameters before execution.
- - This defaults to `true` if not set.
+- `permission_callback` (`callable`, **Required**): A callback function to check if the current user has permission to execute this ability.
+ - The callback receives one optional argument: it can have any type as defined in the input schema (e.g., `array`, `object`, `string`, etc.).
+ - The callback should return a boolean (`true` if the user has permission, `false` otherwise), or a `WP_Error` object on failure.
+ - 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**

includes/abilities-api.php

@@ -31,10 +31,10 @@
  * @phpstan-param array{
  * label?: string,
  * description?: string,
- * input_schema?: array<string,mixed>,
- * output_schema?: array<string,mixed>,
  * execute_callback?: callable( mixed $input= ): (mixed|\WP_Error),
  * permission_callback?: callable( mixed $input= ): (bool|\WP_Error),
+ * input_schema?: array<string,mixed>,
+ * output_schema?: array<string,mixed>,
  * meta?: array<string,mixed>,
  * ability_class?: class-string<\WP_Ability>,
  * ...<string, mixed>

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

@@ -46,18 +46,17 @@ final class WP_Abilities_Registry {
  * @param string $name The name of the ability. The name must be a string containing a namespace
  * prefix, i.e. `my-plugin/my-ability`. It can only contain lowercase
  * alphanumeric characters, dashes and the forward slash.
- * @param array<string,mixed> $args An associative array of arguments for the ability. This should include
- * `label`, `description`, `input_schema`, `output_schema`,
- * `execute_callback`, `permission_callback`, `meta`, and ability_class.
+ * @param array<string,mixed> $args An associative array of arguments for the ability. See wp_register_ability() for
+ * details.
  * @return ?\WP_Ability The registered ability instance on success, null on failure.
  *
  * @phpstan-param array{
  * label?: string,
  * description?: string,
+ * execute_callback?: callable( mixed $input= ): (mixed|\WP_Error),
+ * permission_callback?: callable( mixed $input= ): (bool|\WP_Error),
  * input_schema?: array<string,mixed>,
  * output_schema?: array<string,mixed>,
- * execute_callback?: callable( mixed $input= ): (mixed|\WP_Error),
- * permission_callback?: ?callable( mixed $input= ): (bool|\WP_Error),
  * meta?: array<string,mixed>,
  * ability_class?: class-string<\WP_Ability>,
  * ...<string, mixed>

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

@@ -73,9 +73,9 @@ class WP_Ability {
  * The optional ability permission callback.
  *
  * @since 0.1.0
- * @var ?callable( mixed $input= ): (bool|\WP_Error)
+ * @var callable( mixed $input= ): (bool|\WP_Error)
  */
-	protected $permission_callback = null;
+	protected $permission_callback;
 
 	/**
  * The optional ability metadata.
@@ -143,15 +143,16 @@ public function __construct( string $name, array $args ) {
  * @phpstan-return array{
  * label: string,
  * description: string,
+ * execute_callback: callable( mixed $input= ): (mixed|\WP_Error),
+ * permission_callback: callable( mixed $input= ): (bool|\WP_Error),
  * input_schema?: array<string,mixed>,
  * output_schema?: array<string,mixed>,
- * execute_callback: callable( mixed $input= ): (mixed|\WP_Error),
- * permission_callback?: ?callable( mixed $input= ): (bool|\WP_Error),
  * meta?: array<string,mixed>,
  * ...<string, mixed>,
  * } $args
  */
 	protected function prepare_properties( array $args ): array {
+ // Required args must be present and of the correct type.
  if ( empty( $args['label'] ) || ! is_string( $args['label'] ) ) {
  throw new \InvalidArgumentException(
  esc_html__( 'The ability properties must contain a `label` string.' )
@@ -164,27 +165,28 @@ protected function prepare_properties( array $args ): array {
  );
  }
 
- if ( isset( $args['input_schema'] ) && ! is_array( $args['input_schema'] ) ) {
+ if ( empty( $args['execute_callback'] ) || ! is_callable( $args['execute_callback'] ) ) {
  throw new \InvalidArgumentException(
- esc_html__( 'The ability properties should provide a valid `input_schema` definition.' )
+ esc_html__( 'The ability properties must contain a valid `execute_callback` function.' )
  );
  }
 
- if ( isset( $args['output_schema'] ) && ! is_array( $args['output_schema'] ) ) {
+ if ( empty( $args['permission_callback'] ) || ! is_callable( $args['permission_callback'] ) ) {
  throw new \InvalidArgumentException(
- esc_html__( 'The ability properties should provide a valid `output_schema` definition.' )
+ esc_html__( 'The ability properties must provide a valid `permission_callback` function.' )
  );
  }
 
- if ( empty( $args['execute_callback'] ) || ! is_callable( $args['execute_callback'] ) ) {
+ // Optional args only need to be of the correct type if they are present.
+ if ( isset( $args['input_schema'] ) && ! is_array( $args['input_schema'] ) ) {
  throw new \InvalidArgumentException(
- esc_html__( 'The ability properties must contain a valid `execute_callback` function.' )
+ esc_html__( 'The ability properties should provide a valid `input_schema` definition.' )
  );
  }
 
- if ( isset( $args['permission_callback'] ) && ! is_callable( $args['permission_callback'] ) ) {
+ if ( isset( $args['output_schema'] ) && ! is_array( $args['output_schema'] ) ) {
  throw new \InvalidArgumentException(
- esc_html__( 'The ability properties should provide a valid `permission_callback` function.' )
+ esc_html__( 'The ability properties should provide a valid `output_schema` definition.' )
  );
  }
 
@@ -278,6 +280,7 @@ protected function validate_input( $input = null ) {
  if ( null === $input ) {
  return true;
  }
+
  return new \WP_Error(
  'ability_missing_input_schema',
  sprintf(
@@ -306,8 +309,8 @@ protected function validate_input( $input = null ) {
 
 	/**
  * Checks whether the ability has the necessary permissions.
- * If the permission callback is not set, the default behavior is to allow access
- * when the input provided passes validation.
+ *
+ * The input is validated against the input schema before it is passed to to permission callback.
  *
  * @since 0.1.0
  *
@@ -320,10 +323,6 @@ public function has_permission( $input = null ) {
  return $is_valid;
  }
 
- if ( ! is_callable( $this->permission_callback ) ) {
- return true;
- }
-
  if ( empty( $this->get_input_schema() ) ) {
  return call_user_func( $this->permission_callback );
  }

tests/unit/abilities-api/wpAbilitiesRegistry.php

@@ -112,6 +112,7 @@ public function test_register_invalid_uppercase_characters_in_name() {
  * Should reject ability registration without a label.
  *
  * @covers WP_Abilities_Registry::register
+ * @covers WP_Ability::prepare_properties
  *
  * @expectedIncorrectUsage WP_Abilities_Registry::register
  */
@@ -127,6 +128,7 @@ public function test_register_invalid_missing_label() {
  * Should reject ability registration with invalid label type.
  *
  * @covers WP_Abilities_Registry::register
+ * @covers WP_Ability::prepare_properties
  *
  * @expectedIncorrectUsage WP_Abilities_Registry::register
  */
@@ -141,6 +143,7 @@ public function test_register_invalid_label_type() {
  * Should reject ability registration without a description.
  *
  * @covers WP_Abilities_Registry::register
+ * @covers WP_Ability::prepare_properties
  *
  * @expectedIncorrectUsage WP_Abilities_Registry::register
  */
@@ -156,6 +159,7 @@ public function test_register_invalid_missing_description() {
  * Should reject ability registration with invalid description type.
  *
  * @covers WP_Abilities_Registry::register
+ * @covers WP_Ability::prepare_properties
  *
  * @expectedIncorrectUsage WP_Abilities_Registry::register
  */
@@ -170,6 +174,7 @@ public function test_register_invalid_description_type() {
  * Should reject ability registration without an execute callback.
  *
  * @covers WP_Abilities_Registry::register
+ * @covers WP_Ability::prepare_properties
  *
  * @expectedIncorrectUsage WP_Abilities_Registry::register
  */
@@ -185,6 +190,7 @@ public function test_register_invalid_missing_execute_callback() {
  * Should reject ability registration if the execute callback is not a callable.
  *
  * @covers WP_Abilities_Registry::register
+ * @covers WP_Ability::prepare_properties
  *
  * @expectedIncorrectUsage WP_Abilities_Registry::register
  */
@@ -195,10 +201,27 @@ public function test_register_incorrect_execute_callback_type() {
  $this->assertNull( $result );
 	}
 
+	/**
+ * Should reject ability registration without an execute callback.
+ *
+ * @covers WP_Abilities_Registry::register
+ * @covers WP_Ability::prepare_properties
+ *
+ * @expectedIncorrectUsage WP_Abilities_Registry::register
+ */
+	public function test_register_invalid_missing_permission_callback() {
+ // Remove the permission_callback from the args.
+ unset( self::$test_ability_args['permission_callback'] );
+
+ $result = $this->registry->register( self::$test_ability_name, self::$test_ability_args );
+ $this->assertNull( $result );
+	}
+
 	/**
  * Should reject ability registration if the permission callback is not a callable.
  *
  * @covers WP_Abilities_Registry::register
+ * @covers WP_Ability::prepare_properties
  *
  * @expectedIncorrectUsage WP_Abilities_Registry::register
  */
@@ -213,6 +236,7 @@ public function test_register_incorrect_permission_callback_type() {
  * Should reject ability registration if the input schema is not an array.
  *
  * @covers WP_Abilities_Registry::register
+ * @covers WP_Ability::prepare_properties
  *
  * @expectedIncorrectUsage WP_Abilities_Registry::register
  */
@@ -227,6 +251,7 @@ public function test_register_incorrect_input_schema_type() {
  * Should reject ability registration if the output schema is not an array.
  *
  * @covers WP_Abilities_Registry::register
+ * @covers WP_Ability::prepare_properties
  *
  * @expectedIncorrectUsage WP_Abilities_Registry::register
  */
@@ -241,6 +266,7 @@ public function test_register_incorrect_output_schema_type() {
  * Should reject ability registration with invalid meta type.
  *
  * @covers WP_Abilities_Registry::register
+ * @covers WP_Ability::prepare_properties
  *
  * @expectedIncorrectUsage WP_Abilities_Registry::register
  */

tests/unit/abilities-api/wpRegisterAbility.php

@@ -225,7 +225,6 @@ public function test_register_ability_custom_ability_class(): void {
  );
 	}
 
-
 	/**
  * Tests executing an ability with input not matching schema.
  */

tests/unit/rest-api/wpRestAbilitiesRunController.php

@@ -703,38 +703,6 @@ public function test_ability_without_type_defaults_to_tool(): void {
  $this->assertEquals( 200, $post_response->get_status() );
 	}
 
-	/**
- * Test permission check with null permission callback.
- */
-	public function test_permission_check_passes_when_callback_not_set(): void {
- // Register ability without permission callback.
- wp_register_ability(
- 'test/no-permission-callback',
- array(
- 'label' => 'No Permission Callback',
- 'description' => 'Ability without permission callback',
- 'execute_callback' => static function () {
- return array( 'executed' => true );
- },
- 'meta' => array( 'type' => 'tool' ),
- // No permission_callback set
- )
- );
-
- wp_set_current_user( 0 ); // Not logged in
-
- $request = new WP_REST_Request( 'POST', '/wp/v2/abilities/test/no-permission-callback/run' );
- $request->set_header( 'Content-Type', 'application/json' );
-
- $response = $this->server->dispatch( $request );
-
- // Should succeed when no permission callback is set
- $this->assertEquals( 200, $response->get_status() );
-
- // Restore user for other tests
- wp_set_current_user( self::$user_id );
-	}
-
 	/**
  * Test edge case with empty input for both GET and POST.
  */