[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Comment Check ability for Akismet.
   4   *
   5   * @package Akismet
   6   * @since 5.7
   7   */
   8  
   9  declare( strict_types = 1 );
  10  
  11  /**
  12   * Class Akismet_Ability_Comment_Check
  13   *
  14   * Registers and handles the ability to check comments for spam.
  15   */
  16  class Akismet_Ability_Comment_Check extends Akismet_Ability {
  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/comment-check';
  25      }
  26  
  27      /**
  28       * Get the human-readable label.
  29       *
  30       * @return string The label.
  31       */
  32  	protected function get_label(): string {
  33          return __( 'Check comment for spam', 'akismet' );
  34      }
  35  
  36      /**
  37       * Get the ability description.
  38       *
  39       * @return string The description.
  40       */
  41  	protected function get_description(): string {
  42          return __( 'Checks a comment against the Akismet spam filter to determine if it is spam or legitimate content.', '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'                 => 'object',
  53              'properties'           => array(
  54                  'comment_author'       => array(
  55                      'type'        => 'string',
  56                      'description' => __( 'Name of the comment author.', 'akismet' ),
  57                  ),
  58                  'comment_author_email' => array(
  59                      'type'        => 'string',
  60                      'description' => __( 'Email address of the comment author.', 'akismet' ),
  61                      'format'      => 'email',
  62                  ),
  63                  'comment_author_url'   => array(
  64                      'type'        => 'string',
  65                      'description' => __( 'URL/website of the comment author.', 'akismet' ),
  66                      'format'      => 'uri',
  67                  ),
  68                  'comment_content'      => array(
  69                      'type'        => 'string',
  70                      'description' => __( 'The comment content/text.', 'akismet' ),
  71                  ),
  72                  'comment_type'         => array(
  73                      'type'        => 'string',
  74                      'description' => __( 'The comment type (e.g., "comment", "trackback", "pingback").', 'akismet' ),
  75                      'default'     => 'comment',
  76                  ),
  77                  'comment_post_ID'      => array(
  78                      'type'        => 'integer',
  79                      'description' => __( 'The ID of the post the comment is being submitted to.', 'akismet' ),
  80                  ),
  81                  'permalink'            => array(
  82                      'type'        => 'string',
  83                      'description' => __( 'The permanent link to the post or page.', 'akismet' ),
  84                      'format'      => 'uri',
  85                  ),
  86                  'user_ip'              => array(
  87                      'type'        => 'string',
  88                      'description' => __( 'IP address of the commenter.', 'akismet' ),
  89                  ),
  90                  'user_agent'           => array(
  91                      'type'        => 'string',
  92                      'description' => __( 'User agent string of the web browser submitting the comment.', 'akismet' ),
  93                  ),
  94                  'referrer'             => array(
  95                      'type'        => 'string',
  96                      'description' => __( 'The HTTP_REFERER header.', 'akismet' ),
  97                  ),
  98                  'user_role'            => array(
  99                      'type'        => 'string',
 100                      'description' => __( 'The user role of the comment author if logged in.', 'akismet' ),
 101                  ),
 102              ),
 103              'additionalProperties' => false,
 104          );
 105      }
 106  
 107      /**
 108       * Get the output schema.
 109       *
 110       * @return array The output schema.
 111       */
 112  	protected function get_output_schema(): array {
 113          return array(
 114              'type'                 => 'object',
 115              'properties'           => array(
 116                  'success'    => array(
 117                      'type'        => 'boolean',
 118                      'description' => __( 'Whether the check was successfully performed.', 'akismet' ),
 119                  ),
 120                  'is_spam'    => array(
 121                      'type'        => 'boolean',
 122                      'description' => __( 'Whether the comment is identified as spam.', 'akismet' ),
 123                  ),
 124                  'pro_tip'    => array(
 125                      'type'        => 'string',
 126                      'description' => __( 'Optional recommendation from Akismet (e.g., "discard" for obvious spam).', 'akismet' ),
 127                  ),
 128                  'guid'       => array(
 129                      'type'        => 'string',
 130                      'description' => __( 'Unique identifier for this check, used for webhooks and updates.', 'akismet' ),
 131                  ),
 132                  'error'      => array(
 133                      'type'        => 'string',
 134                      'description' => __( 'Error message if the check could not be completed.', 'akismet' ),
 135                  ),
 136                  'debug_help' => array(
 137                      'type'        => 'string',
 138                      'description' => __( 'Debug information to help troubleshoot issues.', 'akismet' ),
 139                  ),
 140              ),
 141              'additionalProperties' => false,
 142          );
 143      }
 144  
 145      /**
 146       * Get the ability configuration.
 147       *
 148       * @return array The ability configuration.
 149       */
 150  	public function get_config(): array {
 151          return array(
 152              'label'               => $this->get_label(),
 153              'description'         => $this->get_description(),
 154              'category'            => Akismet_Abilities::CATEGORY_SLUG,
 155              'input_schema'        => $this->get_input_schema(),
 156              'output_schema'       => $this->get_output_schema(),
 157              'execute_callback'    => array( $this, 'execute' ),
 158              'permission_callback' => array( $this, 'current_user_has_permission' ),
 159              'meta'                => array(
 160                  'annotations'  => array(
 161                      'readonly'    => true,
 162                      'destructive' => false,
 163                      'idempotent'  => false,
 164                  ),
 165                  'mcp'          => array(
 166                      'public' => ( get_option( 'akismet_enable_mcp_access' ) === '1' ),
 167                      'type'   => 'tool',
 168                  ),
 169                  'show_in_rest' => true,
 170              ),
 171          );
 172      }
 173  
 174      /**
 175       * Execute callback for the comment-check ability.
 176       *
 177       * The nullable $input parameter is required by Akismet_Ability_Interface
 178       * to support abilities that take no input (e.g. get-stats). In practice,
 179       * WP_Ability::execute() validates input against the schema before invoking
 180       * this callback, so null never reaches here — the framework rejects it
 181       * with an "invalid input" error because the schema declares type "object".
 182       *
 183       * @param array|null $input The comment data to check.
 184       * @return array|WP_Error The spam check result or error.
 185       */
 186  	public function execute( ?array $input = null ) {
 187          // Check for required API key.
 188          if ( ! Akismet::get_api_key() ) {
 189              return new WP_Error(
 190                  'akismet_not_configured',
 191                  __( 'Akismet is not configured. Please enter an API key.', 'akismet' )
 192              );
 193          }
 194  
 195          // Perform the comment check.
 196          $result = Akismet::comment_check( $input );
 197  
 198          if ( ! $result ) {
 199              return new WP_Error(
 200                  'comment_check_failed',
 201                  __( 'Failed to check comment with Akismet API.', 'akismet' )
 202              );
 203          }
 204  
 205          // Build response array.
 206          $response = array(
 207              'success' => true,
 208              'is_spam' => $result->is_spam,
 209          );
 210  
 211          // Include optional fields if present.
 212          if ( isset( $result->pro_tip ) ) {
 213              $response['pro_tip'] = $result->pro_tip;
 214          }
 215  
 216          if ( isset( $result->guid ) ) {
 217              $response['guid'] = $result->guid;
 218          }
 219  
 220          if ( isset( $result->error ) ) {
 221              $response['error'] = $result->error;
 222          }
 223  
 224          if ( isset( $result->debug_help ) ) {
 225              $response['debug_help'] = $result->debug_help;
 226          }
 227  
 228          return $response;
 229      }
 230  }