Changeset 61086

Timestamp:

10/29/2025 01:43:52 PM (6 weeks 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.

Location:

trunk/src/wp-includes

Files:

• abilities-api.php (modified) (1 diff)
• abilities-api/class-wp-abilities-registry.php (modified) (1 diff)
• abilities-api/class-wp-ability.php (modified) (5 diffs)

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

@@ -255 +255 @@
  *         Optional. Additional metadata for the ability.
  *
- *         @type array<string, bool|null> $annotations  Optional. Annotation metadata for the ability. Provides
- *                                                      additional semantic information about the ability's
- *                                                      characteristics and behavior.
+ *         @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.
  *                                                      When true, the ability can be invoked via HTTP requests.

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

@@ -62 +62 @@
      *         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.
      *     }

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 );
     }