* Defines WP_Ability class.
* @subpackage Abilities API
declare( strict_types = 1 );
* Encapsulates the properties and methods related to a specific ability in the registry.
* @see WP_Abilities_Registry
* The default value for the `show_in_rest` meta.
protected const DEFAULT_SHOW_IN_REST = false;
* The default ability annotations.
* They are not guaranteed to provide a faithful description of ability behavior.
* @var array<string, bool|null>
protected static $default_annotations = array(
// If true, the ability does not modify its environment.
* If true, the ability may perform destructive updates to its environment.
* If false, the ability performs only additive updates.
* If true, calling the ability repeatedly with the same arguments will have no additional effect
* The name of the ability, with its namespace.
* Example: `my-plugin/my-ability`.
* The human-readable ability label.
* The detailed ability description.
* The optional ability input schema.
* @var array<string, mixed>
protected $input_schema = array();
* The optional ability output schema.
* @var array<string, mixed>
protected $output_schema = array();
* The ability execute callback.
* @var callable( mixed $input= ): (mixed|WP_Error)
protected $execute_callback;
* The optional ability permission callback.
* @var callable( mixed $input= ): (bool|WP_Error)
protected $permission_callback;
* The optional ability metadata.
* @var array<string, mixed>
* Do not use this constructor directly. Instead, use the `wp_register_ability()` function.
* @see wp_register_ability()
* @param string $name The name of the ability, with its namespace.
* @param array<string, mixed> $args {
* An associative array of arguments for the ability.
* @type string $label The human-readable label for the ability.
* @type string $description A detailed description of what the ability does.
* @type string $category The ability category slug this ability belongs to.
* @type callable $execute_callback A callback function to execute when the ability is invoked.
* Receives optional mixed input and returns mixed result or WP_Error.
* @type callable $permission_callback A callback function to check permissions before execution.
* Receives optional mixed input and returns bool or WP_Error.
* @type array<string, mixed> $input_schema Optional. JSON Schema definition for the ability's input.
* @type array<string, mixed> $output_schema Optional. JSON Schema definition for the ability's output.
* @type array<string, mixed> $meta {
* Optional. Additional metadata for the ability.
* @type array<string, bool|null> $annotations {
* Optional. Semantic annotations describing the ability's behavioral characteristics.
* These annotations are hints for tooling and documentation.
* @type bool|null $readonly Optional. If true, the ability does not modify its environment.
* @type bool|null $destructive Optional. If true, the ability may perform destructive updates to its environment.
* If false, the ability performs only additive updates.
* @type bool|null $idempotent Optional. If true, calling the ability repeatedly with the same arguments
* will have no additional effect on its environment.
* @type bool $show_in_rest Optional. Whether to expose this ability in the REST API. Default false.
public function __construct( string $name, array $args ) {
$properties = $this->prepare_properties( $args );
foreach ( $properties as $property_name => $property_value ) {
if ( ! property_exists( $this, $property_name ) ) {
/* translators: %s: Property name. */
__( 'Property "%1$s" is not a valid property for ability "%2$s". Please check the %3$s class for allowed properties.' ),
'<code>' . esc_html( $property_name ) . '</code>',
'<code>' . esc_html( $this->name ) . '</code>',
'<code>' . __CLASS__ . '</code>'
$this->$property_name = $property_value;
* Prepares and validates the properties used to instantiate the ability.
* Errors are thrown as exceptions instead of WP_Errors to allow for simpler handling and overloading. They are then
* caught and converted to a WP_Error when by WP_Abilities_Registry::register().
* @see WP_Abilities_Registry::register()
* @param array<string, mixed> $args {
* An associative array of arguments used to instantiate the ability class.
* @type string $label The human-readable label for the ability.
* @type string $description A detailed description of what the ability does.
* @type string $category The ability category slug this ability belongs to.
* @type callable $execute_callback A callback function to execute when the ability is invoked.
* Receives optional mixed input and returns mixed result or WP_Error.
* @type callable $permission_callback A callback function to check permissions before execution.
* Receives optional mixed input and returns bool or WP_Error.
* @type array<string, mixed> $input_schema Optional. JSON Schema definition for the ability's input. Required if ability accepts an input.
* @type array<string, mixed> $output_schema Optional. JSON Schema definition for the ability's output.
* @type array<string, mixed> $meta {
* Optional. Additional metadata for the ability.
* @type array<string, bool|null> $annotations {
* Optional. Semantic annotations describing the ability's behavioral characteristics.
* These annotations are hints for tooling and documentation.
* @type bool|null $readonly Optional. If true, the ability does not modify its environment.
* @type bool|null $destructive Optional. If true, the ability may perform destructive updates to its environment.
* If false, the ability performs only additive updates.
* @type bool|null $idempotent Optional. If true, calling the ability repeatedly with the same arguments
* will have no additional effect on its environment.
* @type bool $show_in_rest Optional. Whether to expose this ability in the REST API. Default false.
* @return array<string, mixed> {
* An associative array of arguments with validated and prepared properties for the ability class.
* @type string $label The human-readable label for the ability.
* @type string $description A detailed description of what the ability does.
* @type string $category The ability category slug this ability belongs to.
* @type callable $execute_callback A callback function to execute when the ability is invoked.
* Receives optional mixed input and returns mixed result or WP_Error.
* @type callable $permission_callback A callback function to check permissions before execution.
* Receives optional mixed input and returns bool or WP_Error.
* @type array<string, mixed> $input_schema Optional. JSON Schema definition for the ability's input.
* @type array<string, mixed> $output_schema Optional. JSON Schema definition for the ability's output.
* @type array<string, mixed> $meta {
* Additional metadata for the ability.
* @type array<string, bool|null> $annotations {
* Semantic annotations describing the ability's behavioral characteristics.
* These annotations are hints for tooling and documentation.
* @type bool|null $readonly If true, the ability does not modify its environment.
* @type bool|null $destructive If true, the ability may perform destructive updates to its environment.
* If false, the ability performs only additive updates.
* @type bool|null $idempotent If true, calling the ability repeatedly with the same arguments
* will have no additional effect on its environment.
* @type bool $show_in_rest Whether to expose this ability in the REST API. Default false.
* @throws InvalidArgumentException if an argument is invalid.
protected function prepare_properties( array $args ): array {
// Required args must be present and of the correct type.
if ( empty( $args['label'] ) || ! is_string( $args['label'] ) ) {
throw new InvalidArgumentException(
__( 'The ability properties must contain a `label` string.' )
if ( empty( $args['description'] ) || ! is_string( $args['description'] ) ) {
throw new InvalidArgumentException(
__( 'The ability properties must contain a `description` string.' )
if ( empty( $args['category'] ) || ! is_string( $args['category'] ) ) {
throw new InvalidArgumentException(
__( 'The ability properties must contain a `category` string.' )
if ( empty( $args['execute_callback'] ) || ! is_callable( $args['execute_callback'] ) ) {
throw new InvalidArgumentException(
__( 'The ability properties must contain a valid `execute_callback` function.' )
if ( empty( $args['permission_callback'] ) || ! is_callable( $args['permission_callback'] ) ) {
throw new InvalidArgumentException(
__( 'The ability properties must provide a valid `permission_callback` function.' )
// Optional args only need to be of the correct type if they are present.
if ( isset( $args['input_schema'] ) && ! is_array( $args['input_schema'] ) ) {
throw new InvalidArgumentException(
__( 'The ability properties should provide a valid `input_schema` definition.' )
if ( isset( $args['output_schema'] ) && ! is_array( $args['output_schema'] ) ) {
throw new InvalidArgumentException(
__( 'The ability properties should provide a valid `output_schema` definition.' )
if ( isset( $args['meta'] ) && ! is_array( $args['meta'] ) ) {
throw new InvalidArgumentException(
__( 'The ability properties should provide a valid `meta` array.' )
if ( isset( $args['meta']['annotations'] ) && ! is_array( $args['meta']['annotations'] ) ) {
throw new InvalidArgumentException(
__( 'The ability meta should provide a valid `annotations` array.' )
if ( isset( $args['meta']['show_in_rest'] ) && ! is_bool( $args['meta']['show_in_rest'] ) ) {
throw new InvalidArgumentException(
__( 'The ability meta should provide a valid `show_in_rest` boolean.' )
// Set defaults for optional meta.
$args['meta'] = wp_parse_args(
$args['meta'] ?? array(),
'annotations' => static::$default_annotations,
'show_in_rest' => self::DEFAULT_SHOW_IN_REST,
$args['meta']['annotations'] = wp_parse_args(
$args['meta']['annotations'],
static::$default_annotations
* Retrieves the name of the ability, with its namespace.
* Example: `my-plugin/my-ability`.
* @return string The ability name, with its namespace.
public function get_name(): string {
* Retrieves the human-readable label for the ability.
* @return string The human-readable ability label.
public function get_label(): string {
* Retrieves the detailed description for the ability.
* @return string The detailed description for the ability.
public function get_description(): string {
return $this->description;
* Retrieves the ability category for the ability.
* @return string The ability category for the ability.
public function get_category(): string {
* Retrieves the input schema for the ability.
* @return array<string, mixed> The input schema for the ability.
public function get_input_schema(): array {
return $this->input_schema;
* Retrieves the output schema for the ability.
* @return array<string, mixed> The output schema for the ability.
public function get_output_schema(): array {
return $this->output_schema;
* Retrieves the metadata for the ability.
* @return array<string, mixed> The metadata for the ability.
public function get_meta(): array {
* Retrieves a specific metadata item for the ability.
* @param string $key The metadata key to retrieve.
* @param mixed $default_value Optional. The default value to return if the metadata item is not found. Default `null`.
* @return mixed The value of the metadata item, or the default value if not found.
public function get_meta_item( string $key, $default_value = null ) {
return array_key_exists( $key, $this->meta ) ? $this->meta[ $key ] : $default_value;
* Normalizes the input for the ability, applying the default value from the input schema when needed.
* When no input is provided and the input schema is defined with a top-level `default` key, this method returns
* the value of that key. If the input schema does not define a `default`, or if the input schema is empty,
* this method returns null. If input is provided, it is returned as-is.
* @param mixed $input Optional. The raw input provided for the ability. Default `null`.
* @return mixed The same input, or the default from schema, or `null` if default not set.
public function normalize_input( $input = null ) {
$input_schema = $this->get_input_schema();
if ( ! empty( $input_schema ) && array_key_exists( 'default', $input_schema ) ) {
return $input_schema['default'];
* Validates input data against the input schema.
* @param mixed $input Optional. The input data to validate. Default `null`.
* @return true|WP_Error Returns true if valid or the WP_Error object if validation fails.
public function validate_input( $input = null ) {
$input_schema = $this->get_input_schema();
if ( empty( $input_schema ) ) {
'ability_missing_input_schema',
/* translators: %s ability name. */
__( 'Ability "%s" does not define an input schema required to validate the provided input.' ),
$valid_input = rest_validate_value_from_schema( $input, $input_schema, 'input' );
if ( is_wp_error( $valid_input ) ) {
/* translators: %1$s ability name, %2$s error message. */
__( 'Ability "%1$s" has invalid input. Reason: %2$s' ),
$valid_input->get_error_message()
* Invokes a callable, ensuring the input is passed through only if the input schema is defined.
It is recommended that you Edit text format, this type of Fix handles quite a lot in one request
