Represents a registered ability with its configuration, callbacks, and execution logic.

Source: wp-includes/abilities-api/class-wp-ability.php
Since: 6.9.0

Properties

Constants

Static Properties

Methods

__construct()

Instantiates an ability. Do not call directly; use wp_register_ability().

public function __construct( string $name, array $args )

get_name()

Returns the namespaced ability name.

public function get_name(): string

Returns: Ability name (e.g., my-plugin/my-ability)

get_label()

Returns the human-readable label.

public function get_label(): string

get_description()

Returns the detailed description.

public function get_description(): string

get_category()

Returns the category slug.

public function get_category(): string

get_input_schema()

Returns the JSON Schema for input validation.

public function get_input_schema(): array

get_output_schema()

Returns the JSON Schema for output validation.

public function get_output_schema(): array

get_meta()

Returns all metadata.

public function get_meta(): array

get_meta_item()

Returns a specific metadata value.

public function get_meta_item( string $key, mixed $default_value = null ): mixed

normalize_input()

Applies default value from input schema when no input provided.

public function normalize_input( mixed $input = null ): mixed

Returns: Input value, or schema default, or null.

validate_input()

Validates input against the input schema.

public function validate_input( mixed $input = null ): true|WP_Error

Returns: true if valid, WP_Error if validation fails.

Error Codes:

• ability_missing_input_schema — Input provided but no schema defined
• ability_invalid_input — Input fails schema validation

check_permissions()

Checks if execution is permitted. Does not validate input.

public function check_permissions( mixed $input = null ): bool|WP_Error

Returns: true if permitted, false or WP_Error if denied.

Error Codes:

• ability_invalid_permission_callback — Callback not callable

execute()

Executes the ability with full validation and permission checking.

public function execute( mixed $input = null ): mixed|WP_Error

Returns: Execution result or WP_Error on failure.

Execution Flow:

1. normalize_input() — Apply schema defaults
2. validate_input() — Validate against schema
3. check_permissions() — Verify authorization
4. do_action('wp_before_execute_ability') — Pre-execution hook
5. do_execute() — Call execute_callback
6. validate_output() — Validate result against output schema
7. do_action('wp_after_execute_ability') — Post-execution hook

Error Codes:

• ability_invalid_input — Input validation failed
• ability_invalid_permissions — Permission denied
• ability_invalid_execute_callback — Execute callback not callable
• ability_invalid_output — Output validation failed

prepare_properties() (protected)

Validates and prepares configuration arguments.

protected function prepare_properties( array $args ): array

Throws: InvalidArgumentException if required args missing or invalid.

invoke_callback() (protected)

Invokes a callback, passing input only if input schema is defined.

protected function invoke_callback( callable $callback, mixed $input = null ): mixed

do_execute() (protected)

Executes the execute_callback.

protected function do_execute( mixed $input = null ): mixed|WP_Error

validate_output() (protected)

Validates output against output schema.

protected function validate_output( mixed $output ): true|WP_Error

__wakeup()

Prevents unserialization (security hardening).

public function __wakeup(): void

Throws: LogicException

__sleep()

Prevents serialization (security hardening).

public function __sleep(): array

Throws: LogicException

Extending

Custom ability classes must extend WP_Ability:

class My_Custom_Ability extends WP_Ability {
    protected function do_execute( $input = null ) {
        $result = parent::do_execute( $input );
        // Custom post-processing
        return $this->transform( $result );
    }
}

// Register with custom class
wp_register_ability( 'my-plugin/custom', array(
    'ability_class' => 'My_Custom_Ability',
    // ... other args
) );