wpseek.com
Eine auf WordPress spezialiserte Suchmaschine für Entwickler und Theme-Autoren

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 execute and permission callbacks. 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, 'required' => true, ), 'output_schema' => array( 'type' => 'string', 'enum' => array( 'positive', 'negative', 'neutral' ), 'description' => ( 'The sentiment result: positive, negative, or neutral.', 'my-plugin' ), 'required' => true, ), 'execute_callback' => 'my_plugin_analyze_text', 'permission_callback' => 'my_plugin_can_analyze_text', 'meta' => array( 'annotations' => array( 'readonly' => true, ), 'show_in_rest' => true, ), ) ); } add_action( 'wp_abilities_api_init', 'my_plugin_register_abilities' ); ### Naming Conventions Ability names must follow these rules: - Include a namespace prefix (e.g., my-plugin/my-ability). - Use only lowercase alphanumeric characters, dashes, and forward slashes. - Use descriptive, action-oriented names (e.g., process-payment, generate-report). ### Categories Abilities must be organized into categories. Ability categories provide better discoverability and 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 Defining schemas is mandatory when there is a value to pass or return. They ensure data integrity, improve developer experience, and enable better documentation: 'input_schema' => array( 'type' => 'string', 'description' => ( 'The text to be analyzed.', 'my-plugin' ), 'minLength' => 10, 'required' => true, ), 'output_schema' => array( 'type' => 'string', 'enum' => array( 'positive', 'negative', 'neutral' ), 'description' => __( 'The sentiment result: positive, negative, or neutral.', 'my-plugin' ), 'required' => true, ), ### Callbacks #### Execute Callback The execute callback performs the ability's core functionality. It receives optional input data and returns either a result or WP_Error on failure. 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 ); } #### Permission Callback 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: function my_plugin_can_analyze_text( string $input ): bool|WP_Error { return current_user_can( 'edit_posts' ); } ### REST API Integration Abilities can be exposed through the REST API by setting show_in_rest to true in the meta configuration: 'meta' => array( 'show_in_rest' => true, ), This allows abilities to be invoked via HTTP requests to the WordPress REST API.