Refactor the usage of $properties param to $args to align with WordPress usage (#59)

* dev: replace `WP_Ability::validate_properties()` with `::prepare_args()`

* Rename properties to args in `WP_Ability`

* Improve coding style according to conventions

* Update since version

* Fix coding style issue reported in WP core

* Ensure there are no deprecation warning in PHP 8.3+

* Update version to account for the API changes applied

---------

Co-authored-by: Dovid Levine <david@axepress.dev>

Co-authored-by: justlevine <justlevine@git.wordpress.org>
Co-authored-by: gziolo <gziolo@git.wordpress.org>
Co-authored-by: emdashcodes <emdashcodes@git.wordpress.org>

Author: 3 people

abilities-api.php

@@ -12,7 +12,7 @@
  * Plugin URI:        https://github.com/WordPress/abilities-api
  * Description:       Provides a framework for registering and executing AI abilities in WordPress.
  * Requires at least: 6.8
- * Version:           0.1.0
+ * Version:           0.2.0
  * Requires PHP:      7.2
  * Author:            WordPress.org Contributors
  * Author URI:        https://github.com/WordPress/abilities-api/graphs/contributors

includes/abilities-api.php

@@ -22,12 +22,12 @@
  *
  * @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> $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`.
+ * @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{
@@ -40,9 +40,9 @@
  *   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__,
@@ -57,7 +57,7 @@ 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 );
 }
 
 /**

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

@@ -43,12 +43,12 @@ final class WP_Abilities_Registry {
 	 *
 	 * @see wp_register_ability()
 	 *
-	 * @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.
+	 * @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 The registered ability instance on success, null on failure.
 	 *
 	 * @phpstan-param array{
@@ -61,9 +61,9 @@ final class WP_Abilities_Registry {
 	 *   meta?: array<string,mixed>,
 	 *   ability_class?: class-string<\WP_Ability>,
 	 *   ...<string, mixed>
-	 * } $properties
+	 * } $args
 	 */
-	public function register( string $name, array $properties = array() ): ?WP_Ability {
+	public function register( string $name, array $args ): ?WP_Ability {
 		if ( ! preg_match( '/^[a-z0-9-]+\/[a-z0-9-]+$/', $name ) ) {
 			_doing_it_wrong(
 				__METHOD__,
@@ -86,23 +86,20 @@ public function register( string $name, array $properties = array() ): ?WP_Abili
 		}
 
 		// The class is only used to instantiate the ability, and is not a property of the ability itself.
-		if ( isset( $properties['ability_class'] ) && ! is_a( $properties['ability_class'], WP_Ability::class, true ) ) {
+		if ( isset( $args['ability_class'] ) && ! is_a( $args['ability_class'], WP_Ability::class, true ) ) {
 			_doing_it_wrong(
 				__METHOD__,
-				esc_html__( 'The ability properties should provide a valid `ability_class` that extends WP_Ability.' ),
+				esc_html__( 'The ability args should provide a valid `ability_class` that extends WP_Ability.' ),
 				'0.1.0'
 			);
 			return null;
 		}
-		$ability_class = $properties['ability_class'] ?? WP_Ability::class;
-		unset( $properties['ability_class'] );
+		$ability_class = $args['ability_class'] ?? WP_Ability::class;
+		unset( $args['ability_class'] );
 
 		try {
-			// WP_Ability::validate_properties() will throw an exception if the properties are invalid.
-			$ability = new $ability_class(
-				$name,
-				$properties
-			);
+			// WP_Ability::prepare_properties() will throw an exception if the properties are invalid.
+			$ability = new $ability_class( $name, $args );
 		} catch ( \InvalidArgumentException $e ) {
 			_doing_it_wrong(
 				__METHOD__,

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

@@ -96,15 +96,15 @@ class WP_Ability {
 	 *
 	 * @see wp_register_ability()
 	 *
-	 * @param string              $name       The name of the ability, with its namespace.
-	 * @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`, and `meta`.
+	 * @param string              $name The name of the ability, with its namespace.
+	 * @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`, and `meta`.
 	 */
-	public function __construct( string $name, array $properties ) {
+	public function __construct( string $name, array $args ) {
 		$this->name = $name;
 
-		$this->validate_properties( $properties );
+		$properties = $this->prepare_properties( $args );
 
 		foreach ( $properties as $property_name => $property_value ) {
 			if ( ! property_exists( $this, $property_name ) ) {
@@ -126,6 +126,77 @@ public function __construct( string $name, array $properties ) {
 		}
 	}
 
+	/**
+	 * Prepares and validates the properties used to instantiate the ability.
+	 *
+	 * Errors are thrown as exceptions instead of \WP_Errors to allow for simpler handling and overloading. They are then
+	 * caught and converted to a WP_Error when by WP_Abilities_Registry::register().
+	 *
+	 * @since 0.2.0
+	 *
+	 * @see WP_Abilities_Registry::register()
+	 *
+	 * @param array<string,mixed> $args An associative array of arguments used to instantiate the class.
+	 * @return array<string,mixed> The validated and prepared properties.
+	 * @throws \InvalidArgumentException if an argument is invalid.
+	 *
+	 * @phpstan-return array{
+	 *   label: string,
+	 *   description: string,
+	 *   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 {
+		if ( empty( $args['label'] ) || ! is_string( $args['label'] ) ) {
+			throw new \InvalidArgumentException(
+				esc_html__( 'The ability properties must contain a `label` string.' )
+			);
+		}
+
+		if ( empty( $args['description'] ) || ! is_string( $args['description'] ) ) {
+			throw new \InvalidArgumentException(
+				esc_html__( 'The ability properties must contain a `description` string.' )
+			);
+		}
+
+		if ( isset( $args['input_schema'] ) && ! is_array( $args['input_schema'] ) ) {
+			throw new \InvalidArgumentException(
+				esc_html__( 'The ability properties should provide a valid `input_schema` definition.' )
+			);
+		}
+
+		if ( isset( $args['output_schema'] ) && ! is_array( $args['output_schema'] ) ) {
+			throw new \InvalidArgumentException(
+				esc_html__( 'The ability properties should provide a valid `output_schema` definition.' )
+			);
+		}
+
+		if ( empty( $args['execute_callback'] ) || ! is_callable( $args['execute_callback'] ) ) {
+			throw new \InvalidArgumentException(
+				esc_html__( 'The ability properties must contain a valid `execute_callback` function.' )
+			);
+		}
+
+		if ( isset( $args['permission_callback'] ) && ! is_callable( $args['permission_callback'] ) ) {
+			throw new \InvalidArgumentException(
+				esc_html__( 'The ability properties should provide a valid `permission_callback` function.' )
+			);
+		}
+
+		if ( isset( $args['meta'] ) && ! is_array( $args['meta'] ) ) {
+			throw new \InvalidArgumentException(
+				esc_html__( 'The ability properties should provide a valid `meta` array.' )
+			);
+		}
+
+		return $args;
+	}
+
 	/**
 	 * Retrieves the name of the ability, with its namespace.
 	 * Example: `my-plugin/my-ability`.
@@ -193,76 +264,6 @@ public function get_meta(): array {
 		return $this->meta;
 	}
 
-	/**
-	 * Validates the properties used to instantiate the ability.
-	 *
-	 * Errors are thrown as exceptions instead of \WP_Errors to allow for simpler handling and overloading. They are then
-	 * caught and converted to a WP_Error when by WP_Abilities_Registry::register().
-	 *
-	 * @since n.e.x.t
-	 *
-	 * @see WP_Abilities_Registry::register()
-	 *
-	 * @param array<string,mixed> $properties An associative array of properties to validate.
-	 *
-	 * @return void
-	 * @throws \InvalidArgumentException if the properties are invalid.
-	 *
-	 * @phpstan-assert array{
-	 *   label: string,
-	 *   description: string,
-	 *   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>,
-	 * } $properties
-	 */
-	protected function validate_properties( array $properties ) {
-		if ( empty( $properties['label'] ) || ! is_string( $properties['label'] ) ) {
-			throw new \InvalidArgumentException(
-				esc_html__( 'The ability properties must contain a `label` string.' )
-			);
-		}
-
-		if ( empty( $properties['description'] ) || ! is_string( $properties['description'] ) ) {
-			throw new \InvalidArgumentException(
-				esc_html__( 'The ability properties must contain a `description` string.' )
-			);
-		}
-
-		if ( isset( $properties['input_schema'] ) && ! is_array( $properties['input_schema'] ) ) {
-			throw new \InvalidArgumentException(
-				esc_html__( 'The ability properties should provide a valid `input_schema` definition.' )
-			);
-		}
-
-		if ( isset( $properties['output_schema'] ) && ! is_array( $properties['output_schema'] ) ) {
-			throw new \InvalidArgumentException(
-				esc_html__( 'The ability properties should provide a valid `output_schema` definition.' )
-			);
-		}
-
-		if ( empty( $properties['execute_callback'] ) || ! is_callable( $properties['execute_callback'] ) ) {
-			throw new \InvalidArgumentException(
-				esc_html__( 'The ability properties must contain a valid `execute_callback` function.' )
-			);
-		}
-
-		if ( isset( $properties['permission_callback'] ) && ! is_callable( $properties['permission_callback'] ) ) {
-			throw new \InvalidArgumentException(
-				esc_html__( 'The ability properties should provide a valid `permission_callback` function.' )
-			);
-		}
-
-		if ( isset( $properties['meta'] ) && ! is_array( $properties['meta'] ) ) {
-			throw new \InvalidArgumentException(
-				esc_html__( 'The ability properties should provide a valid `meta` array.' )
-			);
-		}
-	}
-
 	/**
 	 * Validates input data against the input schema.
 	 *

includes/bootstrap.php

@@ -19,7 +19,7 @@
 
 // Version of the plugin.
 if ( ! defined( 'WP_ABILITIES_API_VERSION' ) ) {
-	define( 'WP_ABILITIES_API_VERSION', '0.1.0' );
+	define( 'WP_ABILITIES_API_VERSION', '0.2.0' );
 }
 
 // Load core classes if they are not already defined (for non-Composer installs or direct includes).