WP_Ability::prepare_properties( array $args ): array<string,

Description

Parameters

$argsarray

Return

array<string,

mixed&gt; { An associative array of arguments with validated and prepared properties for the ability class.

• $labelstring

  The human-readable label for the ability.

• $descriptionstring

  A detailed description of what the ability does.

• $categorystring

  The ability category slug this ability belongs to.

• $execute_callbackcallable

  A callback function to execute when the ability is invoked. Receives optional mixed input and returns mixed result or WP_Error.

• $permission_callbackcallable

  A callback function to check permissions before execution. Receives optional mixed input and returns bool or WP_Error.

• mixedarray&lt;string,

  &gt; $input_schema Optional. JSON Schema definition for the ability's input.

• mixedarray&lt;string,

  &gt; $output_schema Optional. JSON Schema definition for the ability's output.

• mixedarray&lt;string,

  &gt; $meta { Additional metadata for the ability.

• boolarray&lt;string,

  |null&gt; $annotations { Semantic annotations describing the ability's behavioral characteristics. These annotations are hints for tooling and documentation.

• $readonlybool|null

  If true, the ability does not modify its environment.

• $destructivebool|null

  If true, the ability may perform destructive updates to its environment. If false, the ability performs only additive updates.

• $idempotentbool|null

  If true, calling the ability repeatedly with the same arguments will have no additional effect on its environment. } @type bool $public Whether the ability is meant to be available to clients such as the REST API, MCP, or AI agents. Defaults to false.

• $show_in_restbool

  Whether to expose this ability in the REST API.

Uses · 3

• __()Retrieves the translation of $text.
• wp_parse_args()Merges user defined arguments into defaults array.
• InvalidArgumentException::__construct()

Used by · 1

• WP_Ability::__construct()Constructor.

Source

View on Trac ↗View on GitHub ↗

281	protected function prepare_properties( array $args ): array {282		// Required args must be present and of the correct type.283		if ( empty( $args['label'] ) || ! is_string( $args['label'] ) ) {284			throw new InvalidArgumentException(285				__( 'The ability properties must contain a `label` string.' )286			);287		}288 289		if ( empty( $args['description'] ) || ! is_string( $args['description'] ) ) {290			throw new InvalidArgumentException(291				__( 'The ability properties must contain a `description` string.' )292			);293		}294 295		if ( empty( $args['category'] ) || ! is_string( $args['category'] ) ) {296			throw new InvalidArgumentException(297				__( 'The ability properties must contain a `category` string.' )298			);299		}300 301		// If we are not overriding `ability_class` parameter during instantiation, then we need to validate the execute_callback.302		if ( get_class( $this ) === self::class && ( empty( $args['execute_callback'] ) || ! is_callable( $args['execute_callback'] ) ) ) {303			throw new InvalidArgumentException(304				__( 'The ability properties must contain a valid `execute_callback` function.' )305			);306		}307 308		// If we are not overriding `ability_class` parameter during instantiation, then we need to validate the permission_callback.309		if ( get_class( $this ) === self::class && ( empty( $args['permission_callback'] ) || ! is_callable( $args['permission_callback'] ) ) ) {310			throw new InvalidArgumentException(311				__( 'The ability properties must provide a valid `permission_callback` function.' )312			);313		}314 315		// Optional args only need to be of the correct type if they are present.316		if ( isset( $args['input_schema'] ) && ! is_array( $args['input_schema'] ) ) {317			throw new InvalidArgumentException(318				__( 'The ability properties should provide a valid `input_schema` definition.' )319			);320		}321 322		if ( isset( $args['output_schema'] ) && ! is_array( $args['output_schema'] ) ) {323			throw new InvalidArgumentException(324				__( 'The ability properties should provide a valid `output_schema` definition.' )325			);326		}327 328		if ( isset( $args['meta'] ) && ! is_array( $args['meta'] ) ) {329			throw new InvalidArgumentException(330				__( 'The ability properties should provide a valid `meta` array.' )331			);332		}333 334		if ( isset( $args['meta']['annotations'] ) && ! is_array( $args['meta']['annotations'] ) ) {335			throw new InvalidArgumentException(336				__( 'The ability meta should provide a valid `annotations` array.' )337			);338		}339 340		if ( isset( $args['meta']['show_in_rest'] ) && ! is_bool( $args['meta']['show_in_rest'] ) ) {341			throw new InvalidArgumentException(342				__( 'The ability meta should provide a valid `show_in_rest` boolean.' )343			);344		}345 346		if ( isset( $args['meta']['public'] ) && ! is_bool( $args['meta']['public'] ) ) {347			throw new InvalidArgumentException(348				__( 'The ability meta should provide a valid `public` boolean.' )349			);350		}351 352		// Set defaults for optional meta.353		$args['meta'] = wp_parse_args(354			$args['meta'] ?? array(),355			array(356				'annotations' => static::$default_annotations,357			)358		);359 360		$args['meta']['annotations'] = wp_parse_args(

History

Introduced in 6.9.0. Unchanged from 6.9.7 through 7.1.0.

1. 6.9.7
2. 7.0.4
3. 7.1.0

Signature, return type and hooks compared across 3 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 7.1.0 tag, from src/wp-includes/abilities-api/class-wp-ability.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.