Propose filters to use with the registered ability (#47)

Author: gziolo

includes/abilities-api.php

@@ -7,6 +7,8 @@
  * @package WordPress
  * @subpackage Abilities API
  * @since 0.1.0
+ *
+ * phpcs:disable WordPress.NamingConventions.PrefixAllGlobals
  */
 
 declare( strict_types = 1 );
@@ -34,7 +36,7 @@
  *   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,
+ *   permission_callback?: callable( array<string,mixed> $input ): (bool|\WP_Error),
  *   meta?: array<string,mixed>,
  *   ability_class?: class-string<\WP_Ability>,
  *   ...<string, mixed>

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

@@ -57,7 +57,7 @@ final class WP_Abilities_Registry {
 	 *   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,
+	 *   permission_callback?: ?callable( array<string,mixed> $input ): (bool|\WP_Error),
 	 *   meta?: array<string,mixed>,
 	 *   ability_class?: class-string<\WP_Ability>,
 	 *   ...<string, mixed>

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

@@ -65,15 +65,15 @@ class WP_Ability {
 	 * The ability execute callback.
 	 *
 	 * @since 0.1.0
-	 * @var callable
+	 * @var callable( array<string,mixed> $input): (mixed|\WP_Error)
 	 */
 	protected $execute_callback;
 
 	/**
 	 * The optional ability permission callback.
 	 *
 	 * @since 0.1.0
-	 * @var ?callable
+	 * @var ?callable( array<string,mixed> $input ): (bool|\WP_Error)
 	 */
 	protected $permission_callback = null;
 
@@ -107,7 +107,7 @@ class WP_Ability {
 	 *   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,
+	 *   permission_callback?: ?callable( array<string,mixed> $input ): (bool|\WP_Error),
 	 *   meta?: array<string,mixed>,
 	 *   ...<string, mixed>,
 	 * } $properties
@@ -240,7 +240,7 @@ protected function validate_input( array $input = array() ) {
 	 * @since 0.1.0
 	 *
 	 * @param array<string,mixed> $input Optional. The input data for permission checking.
-	 * @return true|\WP_Error Whether the ability has the necessary permission.
+	 * @return bool|\WP_Error Whether the ability has the necessary permission.
 	 */
 	public function has_permission( array $input = array() ) {
 		$is_valid = $this->validate_input( $input );

phpcs.xml.dist

@@ -60,7 +60,7 @@
 	</rule>
 	<rule ref="WordPress-Extra">
 		<exclude name="WordPress.WP.I18n.MissingArgDomain" />
-		<exclude name="WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedFunctionFound" />
+
 		<!-- Needed to typehint, see: https://github.com/WordPress/WordPress-Coding-Standards/issues/403 -->
 		<exclude name="Generic.Commenting.DocComment.MissingShort" />
 	</rule>
@@ -199,7 +199,7 @@
 				<element value="WP_Ability" />
 				<element value="WP_Abilities" />
 				<element value="WP_REST_Abilities" />
-				<element value="WP_ABILITIES_API" /> <!-- Constant -->
+				<element value="WP_ABILITIES_API" /><!-- Constant -->
 			</property>
 		</properties>
 	</rule>

tests/bootstrap.php

@@ -4,7 +4,6 @@
  *
  * @package abilities-api
  *
- * phpcs:disable WordPress.NamingConventions.PrefixAllGlobals
  * phpcs:disable WordPressVIPMinimum.Files.IncludingFile.UsingVariable
  */
 

tests/unit/abilities-api/wpAbilitiesRegistry.php

@@ -1,6 +1,8 @@
 <?php declare( strict_types=1 );
 
 /**
+ * Tests for the abilities registry functionality.
+ *
  * @covers WP_Abilities_Registry
  *
  * @group abilities-api

tests/unit/abilities-api/wpRegisterAbility.php

@@ -10,6 +10,8 @@ protected function do_execute( array $input ) {
 }
 
 /**
+ * Tests for registering, unregistering and retrieving abilities.
+ *
  * @covers wp_register_ability
  * @covers wp_unregister_ability
  * @covers wp_get_ability
@@ -270,7 +272,7 @@ public function test_execute_ability_no_output_schema_match(): void {
 		);
 		$this->assertWPError(
 			$actual,
-			'Execution should fail due to output not matching schema.',
+			'Execution should fail due to output not matching schema.'
 		);
 		$this->assertSame( 'ability_invalid_output', $actual->get_error_code() );
 		$this->assertSame(
@@ -376,8 +378,6 @@ public function test_unregister_existing_ability() {
 	 * Tests retrieving existing ability.
 	 */
 	public function test_get_existing_ability() {
-		global $wp_abilities;
-
 		$name       = self::$test_ability_name;
 		$properties = self::$test_ability_properties;
 		$callback   = static function ( $instance ) use ( $name, $properties ) {

tests/unit/rest-api/wpRestAbilitiesListController.php

@@ -1,6 +1,8 @@
 <?php declare( strict_types=1 );
 
 /**
+ * Tests for the REST list controller for abilities endpoint.
+ *
  * @covers WP_REST_Abilities_List_Controller
  * @group abilities-api
  * @group rest-api

tests/unit/rest-api/wpRestAbilitiesRunController.php

@@ -1,6 +1,8 @@
 <?php declare( strict_types=1 );
 
 /**
+ * Tests for the REST run controller for abilities endpoint.
+ *
  * @covers WP_REST_Abilities_Run_Controller
  * @group abilities-api
  * @group rest-api