Changeset 61086

Timestamp:

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

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