[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Get Stats ability for Akismet.
   4   *
   5   * @package Akismet
   6   * @since 5.7
   7   */
   8  
   9  declare( strict_types = 1 );
  10  
  11  /**
  12   * Class Akismet_Ability_Get_Stats
  13   *
  14   * Registers and handles the ability to retrieve Akismet statistics.
  15   */
  16  class Akismet_Ability_Get_Stats extends Akismet_Ability implements Akismet_Ability_Interface {
  17  
  18      /**
  19       * Get the ability name.
  20       *
  21       * @return string The ability name.
  22       */
  23  	protected function get_ability_name(): string {
  24          return 'akismet/get-stats';
  25      }
  26  
  27      /**
  28       * Get the human-readable label.
  29       *
  30       * @return string The label.
  31       */
  32  	protected function get_label(): string {
  33          return __( 'Get Akismet statistics', 'akismet' );
  34      }
  35  
  36      /**
  37       * Get the ability description.
  38       *
  39       * @return string The description.
  40       */
  41  	protected function get_description(): string {
  42          return __( 'Retrieves Akismet spam protection statistics including spam blocked count, accuracy percentage, and other key metrics.', 'akismet' );
  43      }
  44  
  45      /**
  46       * Get the input schema.
  47       *
  48       * @return array The input schema.
  49       */
  50  	protected function get_input_schema(): array {
  51          return array(
  52              'type'                 => array( 'object', 'null' ),
  53              'properties'           => array(
  54                  'interval' => array(
  55                      'type'        => 'string',
  56                      'description' => __( 'The time interval for stats. Options: "6-months", "all", or "60-days".', 'akismet' ),
  57                      'enum'        => array( '6-months', 'all', '60-days' ),
  58                      'default'     => '6-months',
  59                  ),
  60              ),
  61              'additionalProperties' => false,
  62          );
  63      }
  64  
  65      /**
  66       * Get the output schema.
  67       *
  68       * @return array The output schema.
  69       */
  70  	protected function get_output_schema(): array {
  71          return array(
  72              'type'                 => 'object',
  73              'properties'           => array(
  74                  'success'         => array(
  75                      'type'        => 'boolean',
  76                      'description' => __( 'Whether the stats were successfully retrieved.', 'akismet' ),
  77                  ),
  78                  'spam'            => array(
  79                      'type'        => 'integer',
  80                      'description' => __( 'Total number of spam comments blocked.', 'akismet' ),
  81                  ),
  82                  'ham'             => array(
  83                      'type'        => 'integer',
  84                      'description' => __( 'Total number of legitimate comments approved.', 'akismet' ),
  85                  ),
  86                  'missed_spam'     => array(
  87                      'type'        => 'integer',
  88                      'description' => __( 'Number of spam comments that were missed.', 'akismet' ),
  89                  ),
  90                  'false_positives' => array(
  91                      'type'        => 'integer',
  92                      'description' => __( 'Number of legitimate comments incorrectly marked as spam.', 'akismet' ),
  93                  ),
  94                  'accuracy'        => array(
  95                      'type'        => 'number',
  96                      'description' => __( 'Accuracy percentage of spam detection.', 'akismet' ),
  97                  ),
  98                  'time_saved'      => array(
  99                      'type'        => 'integer',
 100                      'description' => __( 'Estimated time saved by Akismet blocking spam, in seconds.', 'akismet' ),
 101                  ),
 102                  'breakdown'       => array(
 103                      'type'                 => 'object',
 104                      'description'          => __( 'Monthly breakdown of statistics.', 'akismet' ),
 105                      'additionalProperties' => array(
 106                          'type'       => 'object',
 107                          'properties' => array(
 108                              'spam'            => array(
 109                                  'type'        => 'integer',
 110                                  'description' => __( 'Total number of spam comments blocked in this period.', 'akismet' ),
 111                              ),
 112                              'ham'             => array(
 113                                  'type'        => 'integer',
 114                                  'description' => __( 'Total number of legitimate comments approved in this period.', 'akismet' ),
 115                              ),
 116                              'missed_spam'     => array(
 117                                  'type'        => 'integer',
 118                                  'description' => __( 'Number of spam comments that were missed in this period.', 'akismet' ),
 119                              ),
 120                              'false_positives' => array(
 121                                  'type'        => 'integer',
 122                                  'description' => __( 'Number of legitimate comments incorrectly marked as spam in this period.', 'akismet' ),
 123                              ),
 124                              'da'              => array(
 125                                  'type'        => 'string',
 126                                  'description' => __( 'Date for this period.', 'akismet' ),
 127                              ),
 128                          ),
 129                      ),
 130                  ),
 131                  'interval'        => array(
 132                      'type'        => 'string',
 133                      'description' => __( 'The time interval for these stats.', 'akismet' ),
 134                  ),
 135                  'error'           => array(
 136                      'type'        => 'string',
 137                      'description' => __( 'Error message if the operation could not be completed.', 'akismet' ),
 138                  ),
 139              ),
 140              'additionalProperties' => false,
 141          );
 142      }
 143  
 144      /**
 145       * Get the ability configuration.
 146       *
 147       * @return array The ability configuration.
 148       */
 149  	public function get_config(): array {
 150          return array(
 151              'label'               => $this->get_label(),
 152              'description'         => $this->get_description(),
 153              'category'            => Akismet_Abilities::CATEGORY_SLUG,
 154              'input_schema'        => $this->get_input_schema(),
 155              'output_schema'       => $this->get_output_schema(),
 156              'execute_callback'    => array( $this, 'execute' ),
 157              'permission_callback' => array( $this, 'current_user_has_permission' ),
 158              'meta'                => array(
 159                  'annotations'  => array(
 160                      'readonly'    => true,
 161                      'destructive' => false,
 162                      'idempotent'  => true,
 163                  ),
 164                  'mcp'          => array(
 165                      'public' => ( get_option( 'akismet_enable_mcp_access' ) === '1' ),
 166                      'type'   => 'tool',
 167                  ),
 168                  'show_in_rest' => true,
 169              ),
 170          );
 171      }
 172  
 173      /**
 174       * Execute callback for the get-stats ability.
 175       *
 176       * @param array|null $input The input parameters with optional interval.
 177       * @return array|WP_Error The stats data or error.
 178       */
 179  	public function execute( ?array $input = null ) {
 180          // Get interval from input or use default.
 181          $interval = isset( $input['interval'] ) ? $input['interval'] : '6-months';
 182  
 183          // Fetch stats from Akismet API.
 184          $data = Akismet::get_stats( $interval );
 185  
 186          if ( ! $data ) {
 187              return new WP_Error(
 188                  'stats_fetch_failed',
 189                  __( 'Failed to retrieve stats from Akismet API.', 'akismet' )
 190              );
 191          }
 192  
 193          // Build response with data from API (already properly typed by get_stats).
 194          return array_merge(
 195              array(
 196                  'success'  => true,
 197                  'interval' => $interval,
 198              ),
 199              (array) $data
 200          );
 201      }
 202  }