wpseek.com
A WordPress-centric search engine for devs and theme authors



wp_register_ability › WordPress Function

Since6.9.0
Deprecatedn/a
› wp_register_ability ( $name, $args )
Parameters: (2)
  • (string) $name The name of the ability. Must be a namespaced string containing a prefix, e.g., `my-plugin/my-ability`. Can only contain lowercase alphanumeric characters and dashes, with exactly one slash separating the namespace from the ability name.
    Required: Yes
  • (array<string,mixed>) $args { An associative array of arguments for configuring the ability. @type string $label Required. The human-readable label for the ability. @type string $description Required. A detailed description of what the ability does and when it should be used. @type string $category Required. The registered ability category slug this ability belongs to. Custom categories must be registered via `wp_register_ability_category()` before registering the ability. @type callable $execute_callback Required. A callback function to execute when the ability is invoked. Receives optional mixed input data and must return either a result value (any type) or a `WP_Error` object on failure. @type callable $permission_callback Required unless `$required_capabilities` lists at least one capability. A callback function to check permissions before execution. Receives optional mixed input data (same as `execute_callback`) and must return `true`/`false` for simple checks, or `WP_Error` for detailed error responses. To let everyone run the ability, use `__return_true` with no required capabilities. The `public` meta flag doesn't affect this. It only controls where the ability is shown. @type list<string> $required_capabilities Optional. Minimum capabilities required for every execution of the ability, regardless of input. Each one is checked with `current_user_can()` before `permission_callback` runs. Must be a list of non-empty strings. Check input-dependent requirements in `permission_callback`. Default empty array. @type array<string, mixed> $input_schema Optional. JSON Schema definition for validating the ability's input. Must be a valid JSON Schema object defining the structure and constraints for input data. Used for automatic validation and API documentation. @type array<string, mixed> $output_schema Optional. JSON Schema definition for the ability's output. Describes the structure of successful return values from `execute_callback`. Used for documentation and validation. @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, not enforced behavior. Each annotation defaults to null, indicating that its behavior is unspecified. @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 $public Optional. Whether the ability is meant to be available to clients such as the REST API, MCP, or AI agents. Seeds the default for per-channel flags like `$show_in_rest`. Defaults to false. @type bool $show_in_rest Optional. Whether to expose this ability in the REST API. When true, the ability can be invoked via HTTP requests. Default is the value of `$public` when set, false otherwise. } @type string $ability_class Optional. Fully-qualified custom class name to instantiate instead of the default `WP_Ability` class. The custom class must extend `WP_Ability`. Useful for advanced customization of ability behavior, including callback handling. The default execute and permission callback registration requirements are not enforced for custom classes. }
    Required: Yes
See:
Returns:
  • (WP_Ability|null) The registered ability instance on success, `null` on failure.
Defined at:
Codex:
Change Log:
  • 7.1.0
  • 7.2.0

Registers a new ability using the Abilities API. It requires three steps:

1. Hook into the wp_abilities_api_init action. 2. Call wp_register_ability() with a namespaced name and configuration. 3. Provide an execute_callback. For permission checks, set required_capabilities, permission_callback, or both. Example: function my_plugin_register_abilities(): void { wp_register_ability( 'my-plugin/analyze-text', array( 'label' => ( 'Analyze Text', 'my-plugin' ), 'description' => ( 'Performs sentiment analysis on provided text.', 'my-plugin' ), 'category' => 'text-processing', 'input_schema' => array( 'type' => 'string', 'description' => ( 'The text to be analyzed.', 'my-plugin' ), 'minLength' => 10, ), 'output_schema' => array( 'type' => 'string', 'enum' => array( 'positive', 'negative', 'neutral' ), 'description' => ( 'The sentiment result: positive, negative, or neutral.', 'my-plugin' ), ), 'execute_callback' => 'my_plugin_analyze_text', 'required_capabilities' => array( 'edit_posts' ), 'permission_callback' => 'my_plugin_can_analyze_text', 'meta' => array( 'annotations' => array( 'readonly' => true, ), 'public' => true, ), ) ); } add_action( 'wp_abilities_api_init', 'my_plugin_register_abilities' ); The text-processing category must be registered first with wp_register_ability_category(), or the registration fails. On failure, this function returns null and calls _doing_it_wrong() with the reason. By default, the resulting notice is displayed when WP_DEBUG is enabled. ### Naming Conventions Ability names must follow these rules: - Include exactly one namespace and one ability name, separated by a single slash (e.g., my-plugin/my-ability). Nested namespaces are not supported. - Use only lowercase alphanumeric characters, dashes, and forward slashes. - Use descriptive, action-oriented names (e.g., process-payment, generate-report). ### Categories Every ability must specify a registered category. Categories group related abilities so clients can discover and retrieve relevant subsets. Plugins can reuse an existing category when appropriate, including categories registered by core. Custom categories must be registered on wp_abilities_api_categories_init before abilities that reference them are registered on wp_abilities_api_init: function my_plugin_register_categories(): void { wp_register_ability_category( 'text-processing', array( 'label' => ( 'Text Processing', 'my-plugin' ), 'description' => __( 'Abilities for analyzing and transforming text.', 'my-plugin' ), ) ); } add_action( 'wp_abilities_api_categories_init', 'my_plugin_register_categories' ); ### Input and Output Schemas Schemas define the expected structure, type, and constraints for ability inputs and outputs using JSON Schema syntax. They serve two critical purposes: automatic validation of data passed to and returned from abilities, and self-documenting API contracts for developers. WordPress implements a validator based on a subset of the JSON Schema Version 4 specification (https://json-schema.org/specification-links.html#draft-4). For details on supported JSON Schema properties and syntax, see the related WordPress REST API Schema documentation: https://developer.wordpress.org/rest-api/extending-the-rest-api/schema/#json-schema-basics An input schema is required when passing non-null input. Without one, only null input is accepted and callbacks receive no arguments. When input is null, a top-level default in the input schema is applied before validation. An output schema is optional. When omitted, output schema validation is skipped. Define one to document and validate the result returned by the ability: 'input_schema' => array( 'type' => 'string', 'description' => ( 'The text to be analyzed.', 'my-plugin' ), 'minLength' => 10, ), 'output_schema' => array( 'type' => 'string', 'enum' => array( 'positive', 'negative', 'neutral' ), 'description' => ( 'The sentiment result: positive, negative, or neutral.', 'my-plugin' ), ), ### Callbacks #### Execute Callback The execute callback performs the ability's core functionality. It receives the input prepared by WP_Ability::prepare_input() when an input schema is defined, and no arguments otherwise. It returns either a result or WP_Error on failure. Exceptions thrown by execute or permission callbacks are caught and converted to a WP_Error. function my_plugin_analyze_text( string $input ): string|WP_Error { $score = My_Plugin::perform_sentiment_analysis( $input ); if ( is_wp_error( $score ) ) { return $score; } return My_Plugin::interpret_sentiment_score( $score ); } #### Required Capabilities and Permission Callback Declare only the minimum capabilities required for every execution in required_capabilities. Check additional capabilities that depend on the input in permission_callback. Declaring capabilities needed only for particular inputs can cause discovery to hide an ability the current user is allowed to execute with other inputs. Each required capability is checked with current_user_can() before the permission callback runs. The callback is optional when the list is non-empty. For an ability that everyone may execute, use `return_trueas the callback with no required capabilities. The permission callback determines whether the ability can be executed and must return a boolean orWP_Error. When called throughWP_Ability::execute(), it receives the same prepared input as the execute callback. Common use cases include checking user capabilities, validating API keys, or verifying system state. In the example above, every execution requiresedit_posts, and the callback only adds the check that depends on the input: function my_plugin_can_analyze_text( string $input ): bool|WP_Error { // Only administrators can analyze long texts. if ( mb_strlen( $input ) > 5000 ) { return current_user_can( 'manage_options' ); } return true; } ### Execution Lifecycle CallWP_Ability::execute()to prepare the input, check permissions, invoke the execute callback, and validate output. It returns the result or a WP_Erroron failure. Custom ability classes can override this behavior. Integrations that callWP_Ability::check_permissions()directly must pass it the input returned byWP_Ability::prepare_input(). Hooks run in this order, and processing stops at the first failure: 1.wp_ability_invokedaction, with the raw input. 2.wp_pre_execute_abilityfilter, which can short-circuit the rest of execution. 3.wp_ability_normalize_inputandwp_ability_validate_inputfilters, while the input is prepared. The input validation filter runs only when a non-empty input schema is defined. Sanitization has no filter. 4.wp_ability_permission_resultfilter. 5.wp_before_execute_abilityaction. 6.wp_ability_execute_resultandwp_ability_validate_outputfilters. 7.wp_after_execute_abilityaction. ### Client Exposure Exposure flags do not grant execution permission. Set the high-levelpublicflag to make an ability available to clients such as the REST API, MCP, or AI agents: 'meta' => array( 'public' => true, ), Thepublicflag seeds the default for each per-channel flag. For the REST API it seedsshow_in_rest`, which lets the ability be invoked via HTTP requests. Set a per-channel flag directly to override that default. For example, keep a public ability out of the REST API: 'meta' => array( 'public' => true, 'show_in_rest' => false, ),


Source

function wp_register_ability( string $name, array $args ): ?WP_Ability {
	if ( ! doing_action( 'wp_abilities_api_init' ) ) {
		_doing_it_wrong(
			__FUNCTION__,
			sprintf(
				/* translators: 1: wp_abilities_api_init, 2: string value of the ability name. */
				__( 'Abilities must be registered on the %1$s action. The ability %2$s was not registered.' ),
				'<code>wp_abilities_api_init</code>',
				'<code>' . esc_html( $name ) . '</code>'
			),
			'6.9.0'
		);
		return null;
	}

	$registry = WP_Abilities_Registry::get_instance();
	if ( null === $registry ) {
		return null;
	}

	return $registry->register( $name, $args );
}