From 061019b81a411e6887b4550140a76a5788d42b96 Mon Sep 17 00:00:00 2001 From: Grzegorz Ziolkowski Date: Tue, 30 Sep 2025 10:51:23 +0200 Subject: [PATCH] Rename `check_permission()` to `check_permissions()` on `WP_Ability` --- docs/2.getting-started.md | 45 ++++++++----------- docs/4.using-abilities.md | 38 +++++----------- includes/abilities-api/class-wp-ability.php | 12 ++--- ...class-wp-rest-abilities-run-controller.php | 2 +- .../unit/abilities-api/wpRegisterAbility.php | 10 ++--- 5 files changed, 42 insertions(+), 65 deletions(-) diff --git a/docs/2.getting-started.md b/docs/2.getting-started.md index d6a88c54..1b5b6c2e 100644 --- a/docs/2.getting-started.md +++ b/docs/2.getting-started.md @@ -22,9 +22,9 @@ wp plugin install https://github.com/WordPress/abilities-api/releases/latest/dow "$schema": "https://schemas.wp.org/trunk/wp-env.json", // ... other config ... "plugins": [ - "WordPress/abilities-api", + "WordPress/abilities-api" // ... other plugins ... - ], + ] // ... more config ... } ``` @@ -97,13 +97,13 @@ The below example is for a plugin implementation, but it could also be adapted f ```php check_permission(); - if ( is_wp_error( $permission ) ) { - // Handle permission error - error_log( 'Permission error: ' . $permission->get_error_message() ); - return; - } elseif ( $permission ) { - // Permission granted - safe to execute - $site_title = $ability->execute(); - if ( is_wp_error( $site_title ) ) { - // Handle execution error - error_log( 'Execution error: ' . $site_title->get_error_message() ); - } else { - // $site_title now holds the result of get_bloginfo('name') - // error_log( 'Site Title: ' . $site_title ); - } - } else { - // Permission denied - error_log( 'Permission denied for ability execution' ); - } + $site_title = $ability->execute(); + if ( is_wp_error( $site_title ) ) { + // Handle execution error + error_log( 'Execution error: ' . $site_title->get_error_message() ); + return; } + + // `$site_title` now holds the result of `get_bloginfo( 'name' )`. + echo 'Site Title: ' . esc_html( $site_title ); } ``` diff --git a/docs/4.using-abilities.md b/docs/4.using-abilities.md index 2c5053e1..1ca0cafa 100644 --- a/docs/4.using-abilities.md +++ b/docs/4.using-abilities.md @@ -124,14 +124,9 @@ if ( $ability ) { } ``` -**Checking Permissions (`$ability->check_permission()`)** +**Checking Permissions (`$ability->check_permissions()`)** -Before executing an ability, you can check if the current user has permission. The `check_permission()` method returns either `true`, `false`, or a `WP_Error` object, so you must use `is_wp_error()` to handle errors properly: - -```php -// Method signature: -// check_permission( $input = null ) -``` +You can check if the current user has permissions to execute the ability, also without executing it. The `check_permissions()` method returns either `true`, `false`, or a `WP_Error` object. `true` means permission is granted, `false` means the user simply lacks permission, and a `WP_Error` return value typically indicates a failure in the permission check process (such as an internal error or misconfiguration). You must use `is_wp_error()` to handle errors properly and distinguish between permission denial and actual errors: ```php $ability = wp_get_ability( 'my-plugin/update-option' ); @@ -142,26 +137,17 @@ if ( $ability ) { ); // Check permission before execution - always use is_wp_error() first - $permission = $ability->check_permission( $input ); - if ( is_wp_error( $permission ) ) { - // Handle permission check error (validation, callback error, etc.) - echo 'Permission check failed: ' . $permission->get_error_message(); - } elseif ( $permission ) { - // Permission granted - safe to execute - $result = $ability->execute( $input ); - if ( is_wp_error( $result ) ) { - // Handle execution error - echo 'Execution error: ' . $result->get_error_message(); - } else { - // Use $result - if ( $result['success'] ) { - echo 'Option updated successfully!'; - echo 'Previous value: ' . $result['previous_value']; - } - } + $has_permissions = $ability->check_permissions( $input ); + if ( true === $has_permissions ) { + // Permissions granted – safe to execute. + echo 'You have permissions to execute this ability.'; } else { - // Permission denied - echo 'You do not have permission to execute this ability.'; + // Don't leak permission errors to unauthenticated users. + if ( is_wp_error( $has_permissions ) ) { + error_log( 'Permissions check failed: ' . $has_permissions->get_error_message() ); + } + + echo 'You do not have permissions to execute this ability.'; } } ``` diff --git a/includes/abilities-api/class-wp-ability.php b/includes/abilities-api/class-wp-ability.php index 560233a9..b40bf37e 100644 --- a/includes/abilities-api/class-wp-ability.php +++ b/includes/abilities-api/class-wp-ability.php @@ -317,7 +317,7 @@ protected function validate_input( $input = null ) { * @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 check_permission( $input = null ) { + public function check_permissions( $input = null ) { $is_valid = $this->validate_input( $input ); if ( is_wp_error( $is_valid ) ) { return $is_valid; @@ -335,8 +335,8 @@ public function check_permission( $input = null ) { * * The input is validated against the input schema before it is passed to to permission callback. * - * @deprecated N.E.X.T Use check_permission() instead. - * @see WP_Ability::check_permission() + * @deprecated N.E.X.T Use check_permissions() instead. + * @see WP_Ability::check_permissions() * * @since 0.1.0 * @@ -344,8 +344,8 @@ public function check_permission( $input = null ) { * @return bool|\WP_Error Whether the ability has the necessary permission. */ public function has_permission( $input = null ) { - _deprecated_function( __METHOD__, 'N.E.X.T', 'WP_Ability::check_permission()' ); - return $this->check_permission( $input ); + _deprecated_function( __METHOD__, 'N.E.X.T', 'WP_Ability::check_permissions()' ); + return $this->check_permissions( $input ); } /** @@ -412,7 +412,7 @@ protected function validate_output( $output ) { * @return mixed|\WP_Error The result of the ability execution, or WP_Error on failure. */ public function execute( $input = null ) { - $has_permissions = $this->check_permission( $input ); + $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() ) { diff --git a/includes/rest-api/endpoints/class-wp-rest-abilities-run-controller.php b/includes/rest-api/endpoints/class-wp-rest-abilities-run-controller.php index 699685bb..a54003a5 100644 --- a/includes/rest-api/endpoints/class-wp-rest-abilities-run-controller.php +++ b/includes/rest-api/endpoints/class-wp-rest-abilities-run-controller.php @@ -163,7 +163,7 @@ public function run_ability_permissions_check( $request ) { } $input = $this->get_input_from_request( $request ); - if ( ! $ability->check_permission( $input ) ) { + if ( ! $ability->check_permissions( $input ) ) { return new \WP_Error( 'rest_ability_cannot_execute', __( 'Sorry, you are not allowed to execute this ability.' ), diff --git a/tests/unit/abilities-api/wpRegisterAbility.php b/tests/unit/abilities-api/wpRegisterAbility.php index f25df2b2..a292a118 100644 --- a/tests/unit/abilities-api/wpRegisterAbility.php +++ b/tests/unit/abilities-api/wpRegisterAbility.php @@ -134,7 +134,7 @@ public function test_register_valid_ability(): void { $this->assertSame( self::$test_ability_args['output_schema'], $result->get_output_schema() ); $this->assertSame( self::$test_ability_args['meta'], $result->get_meta() ); $this->assertTrue( - $result->check_permission( + $result->check_permissions( array( 'a' => 2, 'b' => 3, @@ -164,7 +164,7 @@ public function test_register_ability_no_permissions(): void { $result = wp_register_ability( self::$test_ability_name, self::$test_ability_args ); $this->assertFalse( - $result->check_permission( + $result->check_permissions( array( 'a' => 2, 'b' => 3, @@ -289,7 +289,7 @@ public function test_permission_callback_no_input_schema_match(): void { $result = wp_register_ability( self::$test_ability_name, self::$test_ability_args ); - $actual = $result->check_permission( + $actual = $result->check_permissions( array( 'a' => 2, 'b' => 3, @@ -346,7 +346,7 @@ public function test_permission_callback_receives_input(): void { // Test with a > b (should be allowed) $this->assertTrue( - $result->check_permission( + $result->check_permissions( array( 'a' => 5, 'b' => 3, @@ -363,7 +363,7 @@ public function test_permission_callback_receives_input(): void { // Test with a < b (should be denied) $this->assertFalse( - $result->check_permission( + $result->check_permissions( array( 'a' => 2, 'b' => 8,