WP_Abilities_Registry

20final class WP_Abilities_Registry {21	/**22	 * The singleton instance of the registry.23	 *24	 * @since 6.9.025	 * @var self|null26	 */27	private static $instance = null;28 29	/**30	 * Holds the registered abilities.31	 *32	 * @since 6.9.033	 * @var WP_Ability[]34	 */35	private $registered_abilities = array();36 37	/**38	 * Registers a new ability.39	 *40	 * Do not use this method directly. Instead, use the `wp_register_ability()` function.41	 *42	 * @since 6.9.043	 *44	 * @see wp_register_ability()45	 *46	 * @param string               $name The name of the ability. The name must be a string containing a namespace47	 *                                   prefix, i.e. `my-plugin/my-ability`. It can only contain lowercase48	 *                                   alphanumeric characters, dashes and the forward slash.49	 * @param array<string, mixed> $args {50	 *     An associative array of arguments for the ability.51	 *52	 *     @type string               $label                 The human-readable label for the ability.53	 *     @type string               $description           A detailed description of what the ability does.54	 *     @type string               $category              The ability category slug this ability belongs to.55	 *     @type callable             $execute_callback      A callback function to execute when the ability is invoked.56	 *                                                       Receives optional mixed input and returns mixed result or WP_Error.57	 *     @type callable             $permission_callback   A callback function to check permissions before execution.58	 *                                                       Receives optional mixed input and returns bool or WP_Error.59	 *     @type array<string, mixed> $input_schema          Optional. JSON Schema definition for the ability's input.60	 *     @type array<string, mixed> $output_schema         Optional. JSON Schema definition for the ability's output.61	 *     @type array<string, mixed> $meta                  {62	 *         Optional. Additional metadata for the ability.63	 *64	 *         @type array<string, bool|null> $annotations  {65	 *             Optional. Semantic annotations describing the ability's behavioral characteristics.66	 *             These annotations are hints for tooling and documentation.67	 *68	 *             @type bool|null $readonly    Optional. If true, the ability does not modify its environment.69	 *             @type bool|null $destructive Optional. If true, the ability may perform destructive updates to its environment.70	 *                                          If false, the ability performs only additive updates.71	 *             @type bool|null $idempotent  Optional. If true, calling the ability repeatedly with the same arguments72	 *                                          will have no additional effect on its environment.73	 *         }74	 *         @type bool                     $public       Optional. Whether the ability is meant to be available75	 *                                                      to clients such as the REST API, MCP, or AI agents.76	 *                                                      Seeds the default for per-channel flags like77	 *                                                      `$show_in_rest`. Defaults to false.78	 *         @type bool                     $show_in_rest Optional. Whether to expose this ability in the REST API.79	 *                                                      Default is the value of `$public` when set, false otherwise.80	 *     }81	 *     @type string               $ability_class         Optional. Custom class to instantiate instead of WP_Ability.82	 * }83	 * @return WP_Ability|null The registered ability instance on success, null on failure.84	 */85	public function register( string $name, array $args ): ?WP_Ability {86		if ( ! preg_match( '/^[a-z0-9-]+\/[a-z0-9-]+$/', $name ) ) {87			_doing_it_wrong(88				__METHOD__,89				__(90					'Ability name must be a string containing a namespace prefix, i.e. "my-plugin/my-ability". It can only contain lowercase alphanumeric characters, dashes and the forward slash.'91				),92				'6.9.0'93			);94			return null;95		}96 97		if ( $this->is_registered( $name ) ) {98			_doing_it_wrong(99				__METHOD__,