Add serialization methods to WP_Ability and WP_Ability_Category

includes/abilities-api/class-wp-ability-category.php

@@ -18,7 +18,7 @@
  *
  * @see WP_Ability_Categories_Registry
  */
-final class WP_Ability_Category {
+final class WP_Ability_Category implements \JsonSerializable {
 
 	/**
 	 * The unique slug for the ability category.
@@ -192,6 +192,56 @@ public function get_meta(): array {
 		return $this->meta;
 	}
 
+	/**
+	 * Converts the category to an array representation.
+	 *
+	 * Returns a complete array representation of the category including slug, label,
+	 * description, and metadata.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @return array<string,mixed> {
+	 *     The category as an associative array.
+	 *
+	 *     @type string $slug        The unique category slug.
+	 *     @type string $label       The human-readable label.
+	 *     @type string $description The detailed description.
+	 *     @type array  $meta        Optional metadata for the category.
+	 * }
+	 */
+	public function to_array(): array {
+		$array = array(
+			'slug'        => $this->get_slug(),
+			'label'       => $this->get_label(),
+			'description' => $this->get_description(),
+			'meta'        => $this->get_meta(),
+		);
+
+		/**
+		 * Filters the array representation of a category.
+		 *
+		 * @since n.e.x.t
+		 *
+		 * @param array<string,mixed>     $array    The category as an associative array.
+		 * @param \WP_Ability_Category    $category The category instance.
+		 */
+		return apply_filters( "wp_ability_category_{$this->get_slug()}_to_array", $array, $this );
+	}
+
+	/**
+	 * Serializes the category to a value that can be serialized natively by json_encode().
+	 *
+	 * Implements the JsonSerializable interface to allow the category to be passed
+	 * directly to json_encode() without manually calling to_array().
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @return array<string,mixed> The category as an associative array.
+	 */
+	public function jsonSerialize(): array {
+		return $this->to_array();
+	}
+
 	/**
 	 * Wakeup magic method.
 	 *

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

@@ -18,7 +18,7 @@
  *
  * @see WP_Abilities_Registry
  */
-class WP_Ability {
+class WP_Ability implements \JsonSerializable {
 
 	/**
 	 * The default value for the `show_in_rest` meta.
@@ -370,17 +370,6 @@
 		return $this->description;
 	}
 
-	/**
-	 * Retrieves the ability category for the ability.
-	 *
-	 * @since 6.9.0
-	 *
-	 * @return string The ability category for the ability.
-	 */
-	public function get_category(): string {
-		return $this->category;
-	}
-
 	/**
 	 * Retrieves the input schema for the ability.
 	 *
@@ -452,6 +441,134 @@
 		return null;
 	}
 
+	/**
+	 * Retrieves the category for the ability.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @return string The category for the ability.
+	 */
+	public function get_category(): string {
+		return $this->category;
+	}
+
+	/**
+	 * Converts the ability to an array representation.
+	 *
+	 * Returns a complete array representation of the ability including name, label,
+	 * description, schemas, and metadata. Callbacks are excluded as they are not serializable.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @return array<string,mixed> {
+	 *     The ability as an associative array.
+	 *
+	 *     @type string $name          The ability name with namespace.
+	 *     @type string $label         The human-readable label.
+	 *     @type string $description   The detailed description.
+	 *     @type array  $input_schema  The input validation schema.
+	 *     @type array  $output_schema The output validation schema.
+	 *     @type array  $meta {
+	 *         Metadata for the ability. May contain additional custom keys beyond those documented below.
+	 *
+	 *         @type array $annotations {
+	 *             Behavior annotations.
+	 *
+	 *             @type string $instructions Usage instructions.
+	 *             @type bool   $readonly     Whether the ability is read-only.
+	 *             @type bool   $destructive  Whether the ability is destructive.
+	 *             @type bool   $idempotent   Whether the ability is idempotent.
+	 *         }
+	 *         @type bool  $show_in_rest Whether the ability is exposed in REST API.
+	 *         @type mixed ...$0          Additional custom metadata keys.
+	 *     }
+	 * }
+	 */
+	public function to_array(): array {
+		$array = array(
+			'name'          => $this->get_name(),
+			'label'         => $this->get_label(),
+			'description'   => $this->get_description(),
+			'input_schema'  => $this->get_input_schema(),
+			'output_schema' => $this->get_output_schema(),
+			'meta'          => $this->get_meta(),
+		);
+
+		return $array;
+	}
+
+	/**
+	 * Serializes the ability to a value that can be serialized natively by json_encode().
+	 *
+	 * Implements the JsonSerializable interface to allow the ability to be passed
+	 * directly to json_encode() without manually calling to_array().
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @return array<string,mixed> The ability as an associative array.
+	 */
+	public function jsonSerialize(): array {
+		return $this->to_array();
+	}
+
+	/**
+	 * Converts the ability to a JSON Schema representation.
+	 *
+	 * Generates a JSON Schema Draft 4 compliant schema describing the ability's
+	 * structure, including input/output schemas and metadata.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @return array<string,mixed> A JSON Schema representation of the ability.
+	 */
+	public function to_json_schema(): array {
+		$input_schema  = $this->get_input_schema();
+		$output_schema = $this->get_output_schema();
+
+		$schema = array(
+			'$schema'     => 'http://json-schema.org/draft-04/schema#',
+			'type'        => 'object',
+			'title'       => $this->get_label(),
+			'description' => $this->get_description(),
+			'properties'  => array(
+				'name' => array(
+					'type' => 'string',
+					'enum' => array( $this->get_name() ),
+				),
+				'meta' => array(
+					'type'       => 'object',
+					'properties' => array(
+						'annotations'  => array(
+							'type'       => 'object',
+							'properties' => array(
+								'instructions' => array( 'type' => 'string' ),
+								'readonly'     => array( 'type' => 'boolean' ),
+								'destructive'  => array( 'type' => 'boolean' ),
+								'idempotent'   => array( 'type' => 'boolean' ),
+							),
+						),
+						'show_in_rest' => array(
+							'type' => 'boolean',
+						),
+					),
+				),
+			),
+			'required'    => array( 'name', 'meta' ),
+		);
+
+		if ( ! empty( $input_schema ) ) {
+			$schema['properties']['input_schema'] = $input_schema;
+			$schema['required'][]                 = 'input_schema';
+		}
+
+		if ( ! empty( $output_schema ) ) {
+			$schema['properties']['output_schema'] = $output_schema;
+			$schema['required'][]                  = 'output_schema';
+		}
+
+		return $schema;
+	}
+
 	/**
 	 * Validates input data against the input schema.
 	 *