JezK
Edit File: class-akismet-ability-comment-check.php
<?php /** * Comment Check ability for Akismet. * * @package Akismet * @since 5.7 */ declare( strict_types = 1 ); /** * Class Akismet_Ability_Comment_Check * * Registers and handles the ability to check comments for spam. */ class Akismet_Ability_Comment_Check extends Akismet_Ability { /** * Get the ability name. * * @return string The ability name. */ protected function get_ability_name(): string { return 'akismet/comment-check'; } /** * Get the human-readable label. * * @return string The label. */ protected function get_label(): string { return __( 'Check comment for spam', 'akismet' ); } /** * Get the ability description. * * @return string The description. */ protected function get_description(): string { return __( 'Checks a comment against the Akismet spam filter to determine if it is spam or legitimate content.', 'akismet' ); } /** * Get the input schema. * * @return array The input schema. */ protected function get_input_schema(): array { return array( 'type' => 'object', 'properties' => array( 'comment_author' => array( 'type' => 'string', 'description' => __( 'Name of the comment author.', 'akismet' ), ), 'comment_author_email' => array( 'type' => 'string', 'description' => __( 'Email address of the comment author.', 'akismet' ), 'format' => 'email', ), 'comment_author_url' => array( 'type' => 'string', 'description' => __( 'URL/website of the comment author.', 'akismet' ), 'format' => 'uri', ), 'comment_content' => array( 'type' => 'string', 'description' => __( 'The comment content/text.', 'akismet' ), ), 'comment_type' => array( 'type' => 'string', 'description' => __( 'The comment type (e.g., "comment", "trackback", "pingback").', 'akismet' ), 'default' => 'comment', ), 'comment_post_ID' => array( 'type' => 'integer', 'description' => __( 'The ID of the post the comment is being submitted to.', 'akismet' ), ), 'permalink' => array( 'type' => 'string', 'description' => __( 'The permanent link to the post or page.', 'akismet' ), 'format' => 'uri', ), 'user_ip' => array( 'type' => 'string', 'description' => __( 'IP address of the commenter.', 'akismet' ), ), 'user_agent' => array( 'type' => 'string', 'description' => __( 'User agent string of the web browser submitting the comment.', 'akismet' ), ), 'referrer' => array( 'type' => 'string', 'description' => __( 'The HTTP_REFERER header.', 'akismet' ), ), 'user_role' => array( 'type' => 'string', 'description' => __( 'The user role of the comment author if logged in.', 'akismet' ), ), ), 'additionalProperties' => false, ); } /** * Get the output schema. * * @return array The output schema. */ protected function get_output_schema(): array { return array( 'type' => 'object', 'properties' => array( 'success' => array( 'type' => 'boolean', 'description' => __( 'Whether the check was successfully performed.', 'akismet' ), ), 'is_spam' => array( 'type' => 'boolean', 'description' => __( 'Whether the comment is identified as spam.', 'akismet' ), ), 'pro_tip' => array( 'type' => 'string', 'description' => __( 'Optional recommendation from Akismet (e.g., "discard" for obvious spam).', 'akismet' ), ), 'guid' => array( 'type' => 'string', 'description' => __( 'Unique identifier for this check, used for webhooks and updates.', 'akismet' ), ), 'error' => array( 'type' => 'string', 'description' => __( 'Error message if the check could not be completed.', 'akismet' ), ), 'debug_help' => array( 'type' => 'string', 'description' => __( 'Debug information to help troubleshoot issues.', 'akismet' ), ), ), 'additionalProperties' => false, ); } /** * Get the ability configuration. * * @return array The ability configuration. */ public function get_config(): array { return array( 'label' => $this->get_label(), 'description' => $this->get_description(), 'category' => Akismet_Abilities::CATEGORY_SLUG, 'input_schema' => $this->get_input_schema(), 'output_schema' => $this->get_output_schema(), 'execute_callback' => array( $this, 'execute' ), 'permission_callback' => array( $this, 'current_user_has_permission' ), 'meta' => array( 'annotations' => array( 'readonly' => true, 'destructive' => false, 'idempotent' => false, ), 'mcp' => array( 'public' => ( get_option( 'akismet_enable_mcp_access' ) === '1' ), 'type' => 'tool', ), 'show_in_rest' => true, ), ); } /** * Execute callback for the comment-check ability. * * The nullable $input parameter is required by Akismet_Ability_Interface * to support abilities that take no input (e.g. get-stats). In practice, * WP_Ability::execute() validates input against the schema before invoking * this callback, so null never reaches here — the framework rejects it * with an "invalid input" error because the schema declares type "object". * * @param array|null $input The comment data to check. * @return array|WP_Error The spam check result or error. */ public function execute( ?array $input = null ) { // Check for required API key. if ( ! Akismet::get_api_key() ) { return new WP_Error( 'akismet_not_configured', __( 'Akismet is not configured. Please enter an API key.', 'akismet' ) ); } // Perform the comment check. $result = Akismet::comment_check( $input ); if ( ! $result ) { return new WP_Error( 'comment_check_failed', __( 'Failed to check comment with Akismet API.', 'akismet' ) ); } // Build response array. $response = array( 'success' => true, 'is_spam' => $result->is_spam, ); // Include optional fields if present. if ( isset( $result->pro_tip ) ) { $response['pro_tip'] = $result->pro_tip; } if ( isset( $result->guid ) ) { $response['guid'] = $result->guid; } if ( isset( $result->error ) ) { $response['error'] = $result->error; } if ( isset( $result->debug_help ) ) { $response['debug_help'] = $result->debug_help; } return $response; } }