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

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 Abilities can be organized into categories. If no category is provided, the ability is assigned to the built-in uncategorized category. Custom categories must be registered before the abilities that reference them: 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 normalized, validated 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_true as the callback with no required capabilities. The permission callback determines whether the ability can be executed. It receives the same input as the execute callback and must return a boolean or WP_Error. Common use cases include checking user capabilities, validating API keys, or verifying system state. In the example above, every execution requires edit_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 Call WP_Ability::execute() to normalize and validate input, check permissions, invoke the execute callback, and validate output. It returns the result or a WP_Error on failure. Custom ability classes can override this behavior. Hooks run in this order, and processing stops at the first failure: 1. wp_ability_invoked action, with the raw input. 2. wp_pre_execute_ability filter, which can short-circuit the rest of execution. 3. wp_ability_normalize_input, wp_ability_validate_input, and wp_ability_permission_result filters. The input validation filter runs only when a non-empty input schema is defined. 4. wp_before_execute_ability action. 5. wp_ability_execute_result and wp_ability_validate_output filters. 6. wp_after_execute_ability action. ### Client Exposure Exposure flags do not grant execution permission. Set the high-level public flag to make an ability available to clients such as the REST API, MCP, or AI agents: 'meta' => array( 'public' => true, ), The public flag seeds the default for each per-channel flag. For the REST API it seeds show_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, ),