More recent changes from Abilities API

Author: gziolo

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

@@ -84,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(
@@ -93,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

@@ -418,7 +418,7 @@ public function execute( $input = null ) {
 		/**
 		 * Fires before an ability gets executed.
 		 *
-		 * @since n.e.x.t
+		 * @since 0.2.0
 		 *
 		 * @param string $ability_name The name of the ability.
 		 * @param mixed  $input        The input data for the ability.
@@ -438,7 +438,7 @@ public function execute( $input = null ) {
 		/**
 		 * Fires immediately after an ability finished executing.
 		 *
-		 * @since n.e.x.t
+		 * @since 0.2.0
 		 *
 		 * @param string $ability_name The name of the ability.
 		 * @param mixed  $input        The input data for the ability.

tests/phpunit/tests/abilities-api/wpAbilitiesRegistry.php

@@ -27,6 +27,8 @@ public function set_up(): void {
 
 		$this->registry = new WP_Abilities_Registry();
 
+		remove_all_filters( 'register_ability_args' );
+
 		self::$test_ability_args = array(
 			'label'               => 'Add numbers',
 			'description'         => 'Calculates the result of adding two numbers.',
@@ -69,6 +71,8 @@ public function set_up(): void {
 	public function tear_down(): void {
 		$this->registry = null;
 
+		remove_all_filters( 'register_ability_args' );
+
 		parent::tear_down();
 	}
 
@@ -427,4 +431,117 @@ public function test_wp_ability_invalid_properties_throws_exception() {
 			)
 		);
 	}
+
+	/**
+	 * Test register_ability_args filter modifies the args before ability instantiation.
+	 */
+	public function test_register_ability_args_filter_modifies_args() {
+		$was_filter_callback_fired = false;
+
+		// Define the filter.
+		add_filter(
+			'register_ability_args',
+			static function ( $args ) use ( &$was_filter_callback_fired ) {
+				$args['label']             = 'Modified label';
+				$original_execute_callback = $args['execute_callback'];
+				$args['execute_callback']  = static function ( array $input ) use ( &$was_filter_callback_fired, $original_execute_callback ) {
+					$was_filter_callback_fired = true;
+					return $original_execute_callback( $input );
+				};
+
+				return $args;
+			},
+			10
+		);
+
+		// Register the ability.
+		$ability = $this->registry->register( self::$test_ability_name, self::$test_ability_args );
+
+		// Check the label was modified by the filter.
+		$this->assertSame( 'Modified label', $ability->get_label() );
+
+		// Call the execute callback.
+		$result = $ability->execute(
+			array(
+				'a' => 1,
+				'b' => 2,
+			)
+		);
+
+		$this->assertTrue( $was_filter_callback_fired, 'The execute callback defined in the filter was not fired.' );
+		$this->assertSame( 3, $result, 'The original execute callback did not return the expected result.' );
+	}
+
+	/**
+	 * Test register_ability_args filter can block ability registration by returning invalid args.
+	 *
+	 * @expectedIncorrectUsage WP_Abilities_Registry::register
+	 */
+	public function test_register_ability_args_filter_blocks_registration() {
+		// Define the filter.
+		add_filter(
+			'register_ability_args',
+			static function ( $args ) {
+				// Remove the label to make the args invalid.
+				unset( $args['label'] );
+				return $args;
+			},
+			10
+		);
+
+		// Register the ability.
+		$ability = $this->registry->register( self::$test_ability_name, self::$test_ability_args );
+
+		// Check the ability was not registered.
+		$this->assertNull( $ability, 'The ability was registered even though the args were made invalid by the filter.' );
+	}
+
+	/**
+	 * Test register_ability_args filter can block an invalid ability class from being used.
+	 * @expectedIncorrectUsage WP_Abilities_Registry::register
+	 */
+	public function test_register_ability_args_filter_blocks_invalid_ability_class() {
+		// Define the filter.
+		add_filter(
+			'register_ability_args',
+			static function ( $args ) {
+				// Set an invalid ability class.
+				$args['ability_class'] = 'NonExistentClass';
+				return $args;
+			},
+			10
+		);
+		// Register the ability.
+		$ability = $this->registry->register( self::$test_ability_name, self::$test_ability_args );
+
+		// Check the ability was not registered.
+		$this->assertNull( $ability, 'The ability was registered even though the ability class was made invalid by the filter.' );
+	}
+
+	/**
+	 * Tests register_ability_args filter is only applied to the specific ability being registered.
+	 */
+	public function test_register_ability_args_filter_only_applies_to_specific_ability() {
+		add_filter(
+			'register_ability_args',
+			static function ( $args, $name ) {
+				if ( self::$test_ability_name !== $name ) {
+					// Do not modify args for other abilities.
+					return $args;
+				}
+
+				$args['label'] = 'Modified label for specific ability';
+				return $args;
+			},
+			10,
+			2
+		);
+
+		// Register the first ability, which the filter should modify.
+		$filtered_ability = $this->registry->register( self::$test_ability_name, self::$test_ability_args );
+		$this->assertSame( 'Modified label for specific ability', $filtered_ability->get_label() );
+
+		$unfiltered_ability = $this->registry->register( 'test/another-ability', self::$test_ability_args );
+		$this->assertNotSame( $filtered_ability->get_label(), $unfiltered_ability->get_label(), 'The filter incorrectly modified the args for an ability it should not have.' );
+	}
 }