WP_Abilities_Registry::register( string $name, array $args ): WP_Ability|null

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__,100				/* translators: %s: Ability name. */101				sprintf( __( 'Ability "%s" is already registered.' ), esc_html( $name ) ),102				'6.9.0'103			);104			return null;105		}106 107		/**108		 * Filters the ability arguments before they are validated and used to instantiate the ability.109		 *110		 * @since 6.9.0111		 *112		 * @param array<string, mixed> $args {113		 *     An associative array of arguments for the ability.114		 *115		 *     @type string               $label                 The human-readable label for the ability.116		 *     @type string               $description           A detailed description of what the ability does.117		 *     @type string               $category              The ability category slug this ability belongs to.118		 *     @type callable             $execute_callback      A callback function to execute when the ability is invoked.119		 *                                                       Receives optional mixed input and returns mixed result or WP_Error.120		 *     @type callable             $permission_callback   A callback function to check permissions before execution.121		 *                                                       Receives optional mixed input and returns bool or WP_Error.122		 *     @type array<string, mixed> $input_schema          Optional. JSON Schema definition for the ability's input.123		 *     @type array<string, mixed> $output_schema         Optional. JSON Schema definition for the ability's output.124		 *     @type array<string, mixed> $meta                  {125		 *         Optional. Additional metadata for the ability.126		 *127		 *         @type array<string, bool|string> $annotations  Optional. Annotation metadata for the ability.128		 *         @type bool                       $public       Optional. Whether the ability is meant to be129		 *                                                        available to clients such as the REST API, MCP, or AI130		 *                                                        agents. Seeds the default for per-channel flags like131		 *                                                        `$show_in_rest`. Defaults to false.132		 *         @type bool                       $show_in_rest Optional. Whether to expose this ability in the REST API.133		 *                                                        Default is the value of `$public` when set, false otherwise.134		 *     }135		 *     @type string               $ability_class         Optional. Custom class to instantiate instead of WP_Ability.136		 * }137		 * @param string               $name The name of the ability, with its namespace.138		 */139		$args = apply_filters( 'wp_register_ability_args', $args, $name );140 141		// Validate ability category exists if provided (will be validated as required in WP_Ability).142		if ( isset( $args['category'] ) ) {143			if ( ! wp_has_ability_category( $args['category'] ) ) {144				_doing_it_wrong(145					__METHOD__,146					sprintf(147						/* translators: %1$s: ability category slug, %2$s: ability name */148						__( 'Ability category "%1$s" is not registered. Please register the ability category before assigning it to ability "%2$s".' ),149						esc_html( $args['category'] ),150						esc_html( $name )151					),152					'6.9.0'153				);154				return null;155			}156		}157 158		// The class is only used to instantiate the ability, and is not a property of the ability itself.159		if ( isset( $args['ability_class'] ) && ! is_a( $args['ability_class'], WP_Ability::class, true ) ) {160			_doing_it_wrong(161				__METHOD__,162				__( 'The ability args should provide a valid `ability_class` that extends WP_Ability.' ),163				'6.9.0'164			);
When	Instructions	Calls it makes
`!$name`	13	`__(), _doing_it_wrong()`
`$name && ->is_registered()`	24	`->is_registered(), __(), esc_html(), sprintf(), _doing_it_wrong()`
`$name && !->is_registered() && !isset($args)`	34–35	`->is_registered(), apply_filters()`
`$name && !->is_registered() && !is_a()`	34	`->is_registered(), apply_filters(), is_a(), __(), _doing_it_wrong()`
`$name && !->is_registered() && wp_has_ability_category()`	40–41	`->is_registered(), apply_filters(), wp_has_ability_category()`
`$name && !->is_registered() && isset($args) && wp_has_ability_category() && !is_a()`	40	`->is_registered(), apply_filters(), wp_has_ability_category(), is_a(), __(), _doing_it_wrong()`
`$name && !->is_registered() && is_a()`	41–42	`->is_registered(), apply_filters(), is_a()`
`$name && !->is_registered() && isset($args) && !wp_has_ability_category()`	44	`->is_registered(), apply_filters(), wp_has_ability_category(), __(), esc_html(), esc_html(), sprintf(), _doing_it_wrong()`
`$name && !->is_registered() && isset($args) && wp_has_ability_category() && is_a()`	47–48	`->is_registered(), apply_filters(), wp_has_ability_category(), is_a()`
PHP	Compiled	Executed	Branches	Notes
8.6-dev	113	13–48	7
8.5	113	13–48	7
8.4	113	13–48	7	3 fewer instructions than PHP 8.3
8.3	116	16–51	7
8.2	116	16–51	7
8.1	116	16–51	7
7.4	116	16–51	7