From bf036b3d2aea3c96b7e8318e26513ed2f89a1846 Mon Sep 17 00:00:00 2001
From: Dovid Levine <david@axepress.dev>
Date: Sat, 16 Aug 2025 17:20:29 +0300
Subject: [PATCH] dev: add PHPStan array shape for ability `$properties`

---
 includes/abilities-api.php                            | 11 +++++++++++
 .../abilities-api/class-wp-abilities-registry.php     | 11 +++++++++++
 includes/abilities-api/class-wp-ability.php           | 10 ++++++++++
 3 files changed, 32 insertions(+)

diff --git a/includes/abilities-api.php b/includes/abilities-api.php
index ae538a2..3839670 100644
--- a/includes/abilities-api.php
+++ b/includes/abilities-api.php
@@ -27,6 +27,17 @@
  *                                        include `label`, `description`, `input_schema`, `output_schema`,
  *                                        `execute_callback`, `permission_callback`, and `meta`.
  * @return ?\WP_Ability An instance of registered ability on success, null on failure.
+ *
+ * @phpstan-param array{
+ *   label?: string,
+ *   description?: string,
+ *   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,
+ *   meta?: array<string,mixed>,
+ *   ...<string, mixed>
+ * } $properties
  */
 function wp_register_ability( $name, array $properties = array() ): ?WP_Ability {
 	if ( ! did_action( 'abilities_api_init' ) ) {
diff --git a/includes/abilities-api/class-wp-abilities-registry.php b/includes/abilities-api/class-wp-abilities-registry.php
index 0e72925..8e4dc6c 100644
--- a/includes/abilities-api/class-wp-abilities-registry.php
+++ b/includes/abilities-api/class-wp-abilities-registry.php
@@ -42,6 +42,17 @@ final class WP_Abilities_Registry {
 	 *                                        include `label`, `description`, `input_schema`, `output_schema`,
 	 *                                        `execute_callback`, `permission_callback`, and `meta`.
 	 * @return ?\WP_Ability The registered ability instance on success, null on failure.
+	 *
+	 * @phpstan-param array{
+	 *   label?: string,
+	 *   description?: string,
+	 *   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,
+	 *   meta?: array<string,mixed>,
+	 *   ...<string, mixed>
+	 * } $properties
 	 */
 	public function register( $name, array $properties = array() ): ?WP_Ability {
 		$ability = null;
diff --git a/includes/abilities-api/class-wp-ability.php b/includes/abilities-api/class-wp-ability.php
index f5ee8fb..473a2b3 100644
--- a/includes/abilities-api/class-wp-ability.php
+++ b/includes/abilities-api/class-wp-ability.php
@@ -99,6 +99,16 @@ class WP_Ability {
 	 * @param array<string,mixed> $properties An associative array of properties for the ability. This should
 	 *                                        include `label`, `description`, `input_schema`, `output_schema`,
 	 *                                        `execute_callback`, `permission_callback`, and `meta`.
+	 *
+	 * @phpstan-param array{
+	 *   label: string,
+	 *   description: string,
+	 *   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,
+	 *   meta?: array<string,mixed>,
+	 * } $properties
 	 */
 	public function __construct( string $name, array $properties ) {
 		$this->name = $name;