[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Interface for Akismet abilities.
   4   *
   5   * @package Akismet
   6   * @since 5.7
   7   */
   8  
   9  declare( strict_types = 1 );
  10  
  11  /**
  12   * Interface Akismet_Ability_Interface
  13   */
  14  interface Akismet_Ability_Interface {
  15  
  16      /**
  17       * Get the ability configuration array.
  18       *
  19       * Returns the configuration array used to register the ability with wp_register_ability().
  20       *
  21       * @return array {
  22       *     The ability configuration array.
  23       *
  24       *     @type string   $label               A human-readable name for the ability. Used for display purposes. Should be translatable.
  25       *     @type string   $description         A detailed description of what the ability does, its purpose, and its parameters or return values.
  26       *                                         This is crucial for AI agents to understand how and when to use the ability.
  27       *     @type string   $category            The slug of the category this ability belongs to. The category must be registered before
  28       *                                         registering the ability.
  29       *     @type array    $output_schema       A JSON Schema definition describing the expected format of the data returned by the ability.
  30       *                                         Used for validation and documentation.
  31       *     @type callable $execute_callback    The PHP function or method to execute when this ability is called. Receives optional input
  32       *                                         argument matching the input schema type.
  33       *     @type callable $permission_callback A callback function to check if the current user has permission to execute this ability.
  34       *                                         Returns boolean or WP_Error.
  35       *     @type array    $input_schema        Optional. JSON Schema defining expected input parameters. Required when the ability accepts inputs.
  36       *     @type array    $meta                Optional. An associative array for storing arbitrary additional metadata about the ability,
  37       *                                         including 'annotations' (readonly, destructive, idempotent flags) and 'show_in_rest'.
  38       *     @type string   $ability_class       Optional. Custom class name extending WP_Ability for behavior customization.
  39       * }
  40       */
  41  	public function get_config(): array;
  42  
  43      /**
  44       * Execute callback for the ability.
  45       *
  46       * Runs the main functionality of the ability.
  47       *
  48       * @param array|null $input The input parameters for the ability. Null when no input provided.
  49       * @return array|WP_Error The result of the execution or a WP_Error on failure.
  50       */
  51  	public function execute( ?array $input = null );
  52  
  53      /**
  54       * Permission callback for the ability.
  55       *
  56       * Checks if the current user has permission to execute the ability.
  57       *
  58       * @param array|null $input The input parameters for the ability. Null when no input provided.
  59       * @return bool Whether the current user has permission.
  60       */
  61  	public function current_user_has_permission( ?array $input = null ): bool;
  62  }