| [ Index ] |
PHP Cross Reference of WordPress Trunk (Updated Daily) |
[Source view] [Print] [Project Stats]
Abilities API Defines WP_Ability class.
| File Size: | 1081 lines (41 kb) |
| Included or required: | 0 times |
| Referenced: | 0 times |
| Includes or requires: | 0 files |
WP_Ability:: (23 methods):
__construct()
prepare_properties()
get_name()
get_label()
get_description()
get_category()
get_input_schema()
get_output_schema()
get_meta()
get_required_capabilities()
get_meta_item()
normalize_input()
coerce_input()
get_input_error()
validate_input()
is_valid_capability_list()
invoke_callback()
check_permissions()
do_execute()
validate_output()
execute()
__wakeup()
__sleep()
Class: WP_Ability - X-Ref
Encapsulates the properties and methods related to a specific ability in the registry.| __construct( string $name, array $args ) X-Ref |
| Constructor. Do not use this constructor directly. Instead, use the `wp_register_ability()` function. param: string $name The name of the ability, with its namespace. param: array<string, mixed> $args { |
| prepare_properties( array $args ) X-Ref |
| 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 by WP_Abilities_Registry::register(). return: array<string, mixed> { param: array<string, mixed> $args { |
| get_name() X-Ref |
| Retrieves the name of the ability, with its namespace. Example: `my-plugin/my-ability`. return: string The ability name, with its namespace. |
| get_label() X-Ref |
| Retrieves the human-readable label for the ability. return: string The human-readable ability label. |
| get_description() X-Ref |
| Retrieves the detailed description for the ability. return: string The detailed description for the ability. |
| get_category() X-Ref |
| Retrieves the ability category for the ability. return: string The ability category for the ability. |
| get_input_schema() X-Ref |
| Retrieves the input schema for the ability. return: array<string, mixed> The input schema for the ability. |
| get_output_schema() X-Ref |
| Retrieves the output schema for the ability. return: array<string, mixed> The output schema for the ability. |
| get_meta() X-Ref |
| Retrieves the metadata for the ability. return: array<string, mixed> The metadata for the ability. |
| get_required_capabilities() X-Ref |
| Retrieves the capabilities the current user must have to run the ability. return: list<string> The required capabilities. Empty when the ability declares none. |
| get_meta_item( string $key, $default_value = null ) X-Ref |
| Retrieves a specific metadata item for the ability. return: mixed The value of the metadata item, or the default value if not found. 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`. |
| normalize_input( $input = null ) X-Ref |
| 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. The {@see 'wp_ability_normalize_input'} filter fires after the built-in default-value handling, allowing plugins to transform the result. return: mixed The normalized input, or a `WP_Error` if a filter returned one. param: mixed $input Optional. The raw input provided for the ability. Default `null`. |
| coerce_input( $input ) X-Ref |
| Coerces validated input to the types declared in the input schema. Also applies schema format sanitization, such as stripping tags for `text-field` and sanitizing URLs for `uri`, using rest_sanitize_value_from_schema(). Call validate_input() before this method. Coercing unvalidated input can remove unknown properties or cast invalid values, hiding validation errors. This method does not apply defaults or run input validation filters. If sanitization produces an error, including in a nested value, an invalid input error is returned to prevent execution with uncoerced values. return: mixed|WP_Error Coerced input, or WP_Error when it cannot be safely coerced. param: mixed $input Validated ability input. |
| get_input_error( $value ) X-Ref |
| Retrieves the first WP_Error in a sanitized value. return: WP_Error|null The first error found, or null if the value contains no errors. param: mixed $value The value to inspect. |
| validate_input( $input = null ) X-Ref |
| Validates input data against the input schema. return: true|WP_Error Returns true if valid or the WP_Error object if validation fails. param: mixed $input Optional. The input data to validate. Default `null`. |
| is_valid_capability_list( $capabilities ) X-Ref |
| Checks whether a value is a list of non-empty capability strings. return: bool Whether the value is a valid list of capabilities. param: mixed $capabilities The value to check. |
| invoke_callback( callable $callback, $input = null ) X-Ref |
| Invokes a callable, ensuring the input is passed through only if the input schema is defined. return: mixed The result of the callable execution, or a `WP_Error` if the callback threw. param: callable $callback The callable to invoke. param: mixed $input Optional. The input data for the ability. Default `null`. |
| check_permissions( $input = null ) X-Ref |
| Checks whether the ability has the necessary permissions. Please note that input is not automatically validated against the input schema. Use `validate_input()` method to validate input before calling this method if needed. The checks run in this order: 1. When the ability declares `required_capabilities`, each one is checked with `current_user_can()`. The check fails right away if one is missing. 2. When all capabilities pass and the ability has a `permission_callback`, it runs with the given input. The {@see 'wp_ability_permission_result'} filter fires on the final result, allowing plugins to override it. return: bool|WP_Error Whether the ability has the necessary permission. param: mixed $input Optional. The valid input data for permission checking. Default `null`. |
| do_execute( $input = null ) X-Ref |
| Executes the ability callback. The {@see 'wp_ability_execute_result'} filter fires before this method returns, allowing plugins to transform the result produced by the registered `execute_callback`. return: mixed|WP_Error The result of the ability execution, or WP_Error on failure. param: mixed $input Optional. The input data for the ability. Default `null`. |
| validate_output( $output ) X-Ref |
| Validates output data against the output schema. return: true|WP_Error Returns true if valid, or a WP_Error object if validation fails. param: mixed $output The output data to validate. |
| execute( $input = null ) X-Ref |
| Executes the ability after input validation, coercion, and a permission check. Before returning the return value, it also validates the output. return: mixed|WP_Error The result of the ability execution, or WP_Error on failure. param: mixed $input Optional. The input data for the ability. Default `null`. |
| __wakeup() X-Ref |
| Wakeup magic method. |
| __sleep() X-Ref |
| Sleep magic method. |
| Generated : Mon Nov 2 08:20:36 2026 | Cross-referenced by PHPXref |