Changeset 61086 for trunk/src/wp-includes/abilities-api/class-wp-ability.php

Timestamp:

10/29/2025 01:43:52 PM (6 months ago)

Author:

gziolo

Message:

Abilities API: Improve annotations documentation and add permission callback validation

Code quality changes included:

• Expands annotations parameter documentation with detailed descriptions for readonly,

destructive, and idempotent properties.

• Standardizes type order from null|bool to bool|null per coding standards.
• Adds validation check to ensure permission callback is callable before invocation.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/10431.

Follow-up for [61067], [61032].
See #64134.

File:

• trunk/src/wp-includes/abilities-api/class-wp-ability.php (modified) (5 diffs)

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

@@ -34 +34 @@
      *
      * @since 6.9.0
-     * @var array<string, (null|bool)>
+     * @var array<string, bool|null>
      */
     protected static $default_annotations = array(
@@ -151 +151 @@
      *         Optional. Additional metadata for the ability.
      *
-     *         @type array<string, null|bool> $annotations  Optional. Annotation metadata for the ability.
+     *         @type array<string, bool|null> $annotations  {
+     *             Optional. Semantic annotations describing the ability's behavioral characteristics.
+     *             These annotations are hints for tooling and documentation.
+     *
+     *             @type bool|null $readonly    Optional. If true, the ability does not modify its environment.
+     *             @type bool|null $destructive Optional. If true, the ability may perform destructive updates to its environment.
+     *                                          If false, the ability performs only additive updates.
+     *             @type bool|null $idempotent  Optional. If true, calling the ability repeatedly with the same arguments
+     *                                          will have no additional effect on its environment.
+     *         }
      *         @type bool                     $show_in_rest Optional. Whether to expose this ability in the REST API. Default false.
      *     }
@@ -206 +215 @@
      *         Optional. Additional metadata for the ability.
      *
-     *         @type array<string, null|bool> $annotations  Optional. Annotation metadata for the ability.
+     *         @type array<string, bool|null> $annotations  {
+     *             Optional. Semantic annotations describing the ability's behavioral characteristics.
+     *             These annotations are hints for tooling and documentation.
+     *
+     *             @type bool|null $readonly    Optional. If true, the ability does not modify its environment.
+     *             @type bool|null $destructive Optional. If true, the ability may perform destructive updates to its environment.
+     *                                          If false, the ability performs only additive updates.
+     *             @type bool|null $idempotent  Optional. If true, calling the ability repeatedly with the same arguments
+     *                                          will have no additional effect on its environment.
+     *         }
      *         @type bool                     $show_in_rest Optional. Whether to expose this ability in the REST API. Default false.
      *     }
@@ -225 +243 @@
      *         Additional metadata for the ability.
      *
-     *         @type array<string, null|bool> $annotations  Optional. Annotation metadata for the ability.
+     *         @type array<string, bool|null> $annotations  {
+     *             Semantic annotations describing the ability's behavioral characteristics.
+     *             These annotations are hints for tooling and documentation.
+     *
+     *             @type bool|null $readonly    If true, the ability does not modify its environment.
+     *             @type bool|null $destructive If true, the ability may perform destructive updates to its environment.
+     *                                          If false, the ability performs only additive updates.
+     *             @type bool|null $idempotent  If true, calling the ability repeatedly with the same arguments
+     *                                          will have no additional effect on its environment.
+     *         }
      *         @type bool                     $show_in_rest Whether to expose this ability in the REST API. Default false.
      *     }
@@ -499 +526 @@
      */
     public function check_permissions( $input = null ) {
+        if ( ! is_callable( $this->permission_callback ) ) {
+            return new WP_Error(
+                'ability_invalid_permission_callback',
+                /* translators: %s ability name. */
+                sprintf( __( 'Ability "%s" does not have a valid permission callback.' ), esc_html( $this->name ) )
+            );
+        }
+
         return $this->invoke_callback( $this->permission_callback, $input );
     }