Bring another set of upstream changes planned for v0.2.0 release

Author: gziolo

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

@@ -39,16 +39,16 @@ final class WP_Abilities_Registry {
 	 *
 	 * Do not use this method directly. Instead, use the `wp_register_ability()` function.
 	 *
-	 * @see wp_register_ability()
-	 *
 	 * @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_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> $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__,
@@ -85,87 +85,30 @@ public function register( string $name, array $properties = array() ): ?WP_Abili
 			return null;
 		}
 
-		if ( empty( $properties['label'] ) || ! is_string( $properties['label'] ) ) {
-			_doing_it_wrong(
-				__METHOD__,
-				esc_html__( 'The ability properties must contain a `label` string.' ),
-				'0.1.0'
-			);
-			return null;
-		}
-
-		if ( empty( $properties['description'] ) || ! is_string( $properties['description'] ) ) {
-			_doing_it_wrong(
-				__METHOD__,
-				esc_html__( 'The ability properties must contain a `description` string.' ),
-				'0.1.0'
-			);
-			return null;
-		}
-
-		if ( isset( $properties['input_schema'] ) && ! is_array( $properties['input_schema'] ) ) {
-			_doing_it_wrong(
-				__METHOD__,
-				esc_html__( 'The ability properties should provide a valid `input_schema` definition.' ),
-				'0.1.0'
-			);
-			return null;
-		}
-
-		if ( isset( $properties['output_schema'] ) && ! is_array( $properties['output_schema'] ) ) {
-			_doing_it_wrong(
-				__METHOD__,
-				esc_html__( 'The ability properties should provide a valid `output_schema` definition.' ),
-				'0.1.0'
-			);
-			return null;
-		}
-
-		if ( empty( $properties['execute_callback'] ) || ! is_callable( $properties['execute_callback'] ) ) {
-			_doing_it_wrong(
-				__METHOD__,
-				esc_html__( 'The ability properties must contain a valid `execute_callback` function.' ),
-				'0.1.0'
-			);
-			return null;
-		}
-
-		if ( isset( $properties['permission_callback'] ) && ! is_callable( $properties['permission_callback'] ) ) {
-			_doing_it_wrong(
-				__METHOD__,
-				esc_html__( 'The ability properties should provide a valid `permission_callback` function.' ),
-				'0.1.0'
-			);
-			return null;
-		}
-
-		if ( isset( $properties['meta'] ) && ! is_array( $properties['meta'] ) ) {
+		// 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(
 				__METHOD__,
-				esc_html__( 'The ability properties should provide a valid `meta` array.' ),
+				esc_html__( 'The ability args should provide a valid `ability_class` that extends WP_Ability.' ),
 				'0.1.0'
 			);
 			return null;
 		}
+		$ability_class = $args['ability_class'] ?? WP_Ability::class;
+		unset( $args['ability_class'] );
 
-		if ( isset( $properties['ability_class'] ) && ! is_a( $properties['ability_class'], WP_Ability::class, true ) ) {
+		try {
+			// 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__,
-				esc_html__( 'The ability properties should provide a valid `ability_class` that extends WP_Ability.' ),
+				esc_html( $e->getMessage() ),
 				'0.1.0'
 			);
 			return null;
 		}
 
-		// The class is only used to instantiate the ability, and is not a property of the ability itself.
-		$ability_class = $properties['ability_class'] ?? WP_Ability::class;
-		unset( $properties['ability_class'] );
-
-		$ability = new $ability_class(
-			$name,
-			$properties
-		);
-
 		$this->registered_abilities[ $name ] = $ability;
 		return $ability;
 	}
@@ -175,10 +118,10 @@ public function register( string $name, array $properties = array() ): ?WP_Abili
 	 *
 	 * Do not use this method directly. Instead, use the `wp_unregister_ability()` function.
 	 *
-	 * @see wp_unregister_ability()
-	 *
 	 * @since 0.1.0
 	 *
+	 * @see wp_unregister_ability()
+	 *
 	 * @param string $name The name of the registered ability, with its namespace.
 	 * @return ?\WP_Ability The unregistered ability instance on success, null on failure.
 	 */
@@ -204,10 +147,10 @@ public function unregister( string $name ): ?WP_Ability {
 	 *
 	 * Do not use this method directly. Instead, use the `wp_get_abilities()` function.
 	 *
-	 * @see wp_get_abilities()
-	 *
 	 * @since 0.1.0
 	 *
+	 * @see wp_get_abilities()
+	 *
 	 * @return \WP_Ability[] The array of registered abilities.
 	 */
 	public function get_all_registered(): array {
@@ -231,10 +174,10 @@ public function is_registered( string $name ): bool {
 	 *
 	 * Do not use this method directly. Instead, use the `wp_get_ability()` function.
 	 *
-	 * @see wp_get_ability()
-	 *
 	 * @since 0.1.0
 	 *
+	 * @see wp_get_ability()
+	 *
 	 * @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.
 	 */

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

@@ -92,29 +92,20 @@ class WP_Ability {
 	 *
 	 * @access private
 	 *
-	 * @see wp_register_ability()
-	 *
 	 * @since 0.1.0
 	 *
-	 * @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`.
+	 * @see wp_register_ability()
 	 *
-	 * @phpstan-param 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
+	 * @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;
 
+		$properties = $this->prepare_properties( $args );
+
 		foreach ( $properties as $property_name => $property_value ) {
 			if ( ! property_exists( $this, $property_name ) ) {
 				_doing_it_wrong(
@@ -135,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`.

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

@@ -2,8 +2,9 @@
 /**
  * REST API list controller for Abilities API.
  *
- * @package abilities-api
- * @since   0.1.0
+ * @package WordPress
+ * @subpackage Abilities_API
+ * @since 0.1.0
  */
 
 declare( strict_types = 1 );

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

@@ -2,8 +2,9 @@
 /**
  * REST API run controller for Abilities API.
  *
- * @package abilities-api
- * @since   0.1.0
+ * @package WordPress
+ * @subpackage Abilities_API
+ * @since 0.1.0
  */
 
 declare( strict_types = 1 );