Sync changes from Abilities API targeted for v0.2.0

Author: gziolo

src/wp-includes/abilities-api.php

@@ -5,7 +5,7 @@
  * Defines functions for managing abilities in WordPress.
  *
  * @package WordPress
- * @subpackage Abilities API
+ * @subpackage Abilities_API
  * @since 0.1.0
  */
 
@@ -16,31 +16,31 @@
  *
  * Note: Do not use before the {@see 'abilities_api_init'} hook.
  *
- * @see WP_Abilities_Registry::register()
- *
  * @since 0.1.0
  *
- * @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> $properties An associative array of properties for the ability. This should include
- *                                        `label`, `description`, `input_schema`, `output_schema`, `execute_callback`,
- *                                        `permission_callback`, `meta`, and `ability_class`.
+ * @see WP_Abilities_Registry::register()
+ *
+ * @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`.
  * @return ?\WP_Ability An instance of registered ability 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( array<string,mixed> $input): (mixed|\WP_Error),
- *   permission_callback?: callable( array<string,mixed> $input ): (bool|\WP_Error),
  *   meta?: array<string,mixed>,
  *   ability_class?: class-string<\WP_Ability>,
  *   ...<string, mixed>
- * } $properties
+ * } $args
  */
-function wp_register_ability( string $name, array $properties = array() ): ?WP_Ability {
+function wp_register_ability( string $name, array $args ): ?WP_Ability {
 	if ( ! did_action( 'abilities_api_init' ) ) {
 		_doing_it_wrong(
 			__FUNCTION__,
@@ -55,16 +55,16 @@ function wp_register_ability( string $name, array $properties = array() ): ?WP_A
 		return null;
 	}
 
-	return WP_Abilities_Registry::get_instance()->register( $name, $properties );
+	return WP_Abilities_Registry::get_instance()->register( $name, $args );
 }
 
 /**
  * Unregisters an ability using Abilities API.
  *
- * @see WP_Abilities_Registry::unregister()
- *
  * @since 0.1.0
  *
+ * @see WP_Abilities_Registry::unregister()
+ *
  * @param string $name The name of the registered ability, with its namespace.
  * @return ?\WP_Ability The unregistered ability instance on success, null on failure.
  */
@@ -75,10 +75,10 @@ function wp_unregister_ability( string $name ): ?WP_Ability {
 /**
  * Retrieves a registered ability using Abilities API.
  *
- * @see WP_Abilities_Registry::get_registered()
- *
  * @since 0.1.0
  *
+ * @see WP_Abilities_Registry::get_registered()
+ *
  * @param string $name The name of the registered ability, with its namespace.
  * @return ?\WP_Ability The registered ability instance, or null if it is not registered.
  */
@@ -89,10 +89,10 @@ function wp_get_ability( string $name ): ?WP_Ability {
 /**
  * Retrieves all registered abilities using Abilities API.
  *
- * @see WP_Abilities_Registry::get_all_registered()
- *
  * @since 0.1.0
  *
+ * @see WP_Abilities_Registry::get_all_registered()
+ *
  * @return \WP_Ability[] The array of registered abilities.
  */
 function wp_get_abilities(): array {

src/wp-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( array<string,mixed> $input): (mixed|\WP_Error),
-	 *   permission_callback?: ?callable( array<string,mixed> $input ): (bool|\WP_Error),
 	 *   meta?: array<string,mixed>,
 	 *   ability_class?: class-string<\WP_Ability>,
 	 *   ...<string, mixed>
@@ -85,6 +84,16 @@ public function register( string $name, array $args ): ?WP_Ability {
 			return null;
 		}
 
+		/**
+		 * Filters the ability arguments before they are validated and used to instantiate the ability.
+		 *
+		 * @since 0.2.0
+		 *
+		 * @param array<string,mixed> $args The arguments used to instantiate the ability.
+		 * @param string              $name The name of the ability, with its namespace.
+		 */
+		$args = apply_filters( 'register_ability_args', $args, $name );
+
 		// The class is only used to instantiate the ability, and is not a property of the ability itself.
 		if ( isset( $args['ability_class'] ) && ! is_a( $args['ability_class'], WP_Ability::class, true ) ) {
 			_doing_it_wrong(
@@ -94,6 +103,8 @@ public function register( string $name, array $args ): ?WP_Ability {
 			);
 			return null;
 		}
+
+		/** @var class-string<\WP_Ability> */
 		$ability_class = $args['ability_class'] ?? WP_Ability::class;
 		unset( $args['ability_class'] );
 

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

@@ -65,17 +65,17 @@ class WP_Ability {
 	 * The ability execute callback.
 	 *
 	 * @since 0.1.0
-	 * @var callable( array<string,mixed> $input): (mixed|\WP_Error)
+	 * @var callable( mixed $input= ): (mixed|\WP_Error)
 	 */
 	protected $execute_callback;
 
 	/**
 	 * The optional ability permission callback.
 	 *
 	 * @since 0.1.0
-	 * @var ?callable( array<string,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( array<string,mixed> $input): (mixed|\WP_Error),
-	 *   permission_callback?: ?callable( array<string,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.' )
 			);
 		}
 
@@ -269,13 +271,24 @@ public function get_meta(): array {
 	 *
 	 * @since 0.1.0
 	 *
-	 * @param array<string,mixed> $input Optional. The input data to validate.
+	 * @param mixed $input Optional. The input data to validate. Default `null`.
 	 * @return true|\WP_Error Returns true if valid or the WP_Error object if validation fails.
 	 */
-	protected function validate_input( array $input = array() ) {
+	protected function validate_input( $input = null ) {
 		$input_schema = $this->get_input_schema();
 		if ( empty( $input_schema ) ) {
-			return true;
+			if ( null === $input ) {
+				return true;
+			}
+
+			return new \WP_Error(
+				'ability_missing_input_schema',
+				sprintf(
+					/* translators: %s ability name. */
+					__( 'Ability "%s" does not define an input schema required to validate the provided input.' ),
+					$this->name
+				)
+			);
 		}
 
 		$valid_input = rest_validate_value_from_schema( $input, $input_schema, 'input' );
@@ -296,36 +309,54 @@ protected function validate_input( array $input = array() ) {
 
 	/**
 	 * 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.
 	 *
-	 * @since 0.1.0
+	 * The input is validated against the input schema before it is passed to to permission callback.
 	 *
-	 * @param array<string,mixed> $input Optional. The input data for permission checking.
+	 * @since 0.2.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( array $input = array() ) {
+	public function check_permissions( $input = null ) {
 		$is_valid = $this->validate_input( $input );
 		if ( is_wp_error( $is_valid ) ) {
 			return $is_valid;
 		}
 
-		if ( ! is_callable( $this->permission_callback ) ) {
-			return true;
+		if ( empty( $this->get_input_schema() ) ) {
+			return call_user_func( $this->permission_callback );
 		}
 
 		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 0.2.0 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__, '0.2.0', 'WP_Ability::check_permissions()' );
+		return $this->check_permissions( $input );
+	}
+
 	/**
 	 * Executes the ability callback.
 	 *
 	 * @since 0.1.0
 	 *
-	 * @param array<string,mixed> $input The input data for the ability.
+	 * @param mixed $input Optional. The input data for the ability. Default `null`.
 	 * @return mixed|\WP_Error The result of the ability execution, or WP_Error on failure.
 	 */
-	protected function do_execute( array $input ) {
+	protected function do_execute( $input = null ) {
 		if ( ! is_callable( $this->execute_callback ) ) {
 			return new \WP_Error(
 				'ability_invalid_execute_callback',
@@ -334,6 +365,10 @@ protected function do_execute( array $input ) {
 			);
 		}
 
+		if ( empty( $this->get_input_schema() ) ) {
+			return call_user_func( $this->execute_callback );
+		}
+
 		return call_user_func( $this->execute_callback, $input );
 	}
 
@@ -373,11 +408,11 @@ protected function validate_output( $output ) {
 	 *
 	 * @since 0.1.0
 	 *
-	 * @param array<string,mixed> $input Optional. The input data for the ability.
+	 * @param mixed $input Optional. The input data for the ability. Default `null`.
 	 * @return mixed|\WP_Error The result of the ability execution, or WP_Error on failure.
 	 */
-	public function execute( array $input = array() ) {
-		$has_permissions = $this->has_permission( $input );
+	public function execute( $input = null ) {
+		$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() ) {
@@ -398,14 +433,38 @@ public function execute( array $input = array() ) {
 			);
 		}
 
+		/**
+		 * Fires before an ability gets executed.
+		 *
+		 * @since 0.2.0
+		 *
+		 * @param string $ability_name The name of the ability.
+		 * @param mixed  $input        The input data for the ability.
+		 */
+		do_action( 'before_execute_ability', $this->name, $input );
+
 		$result = $this->do_execute( $input );
 		if ( is_wp_error( $result ) ) {
 			return $result;
 		}
 
 		$is_valid = $this->validate_output( $result );
+		if ( is_wp_error( $is_valid ) ) {
+			return $is_valid;
+		}
 
-		return is_wp_error( $is_valid ) ? $is_valid : $result;
+		/**
+		 * Fires immediately after an ability finished executing.
+		 *
+		 * @since 0.2.0
+		 *
+		 * @param string $ability_name The name of the ability.
+		 * @param mixed  $input        The input data for the ability.
+		 * @param mixed  $result       The result of the ability execution.
+		 */
+		do_action( 'after_execute_ability', $this->name, $input, $result );
+
+		return $result;
 	}
 
 	/**