first commit
This commit is contained in:
Roman Pyrih
@@ -0,0 +1,224 @@
|
||||
<?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 implements Akismet_Ability_Interface {
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*
|
||||
* @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;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,202 @@
|
||||
<?php
|
||||
/**
|
||||
* Get Stats ability for Akismet.
|
||||
*
|
||||
* @package Akismet
|
||||
* @since 5.7
|
||||
*/
|
||||
|
||||
declare( strict_types = 1 );
|
||||
|
||||
/**
|
||||
* Class Akismet_Ability_Get_Stats
|
||||
*
|
||||
* Registers and handles the ability to retrieve Akismet statistics.
|
||||
*/
|
||||
class Akismet_Ability_Get_Stats extends Akismet_Ability implements Akismet_Ability_Interface {
|
||||
|
||||
/**
|
||||
* Get the ability name.
|
||||
*
|
||||
* @return string The ability name.
|
||||
*/
|
||||
protected function get_ability_name(): string {
|
||||
return 'akismet/get-stats';
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the human-readable label.
|
||||
*
|
||||
* @return string The label.
|
||||
*/
|
||||
protected function get_label(): string {
|
||||
return __( 'Get Akismet statistics', 'akismet' );
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the ability description.
|
||||
*
|
||||
* @return string The description.
|
||||
*/
|
||||
protected function get_description(): string {
|
||||
return __( 'Retrieves Akismet spam protection statistics including spam blocked count, accuracy percentage, and other key metrics.', 'akismet' );
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the input schema.
|
||||
*
|
||||
* @return array The input schema.
|
||||
*/
|
||||
protected function get_input_schema(): array {
|
||||
return array(
|
||||
'type' => array( 'object', 'null' ),
|
||||
'properties' => array(
|
||||
'interval' => array(
|
||||
'type' => 'string',
|
||||
'description' => __( 'The time interval for stats. Options: "6-months", "all", or "60-days".', 'akismet' ),
|
||||
'enum' => array( '6-months', 'all', '60-days' ),
|
||||
'default' => '6-months',
|
||||
),
|
||||
),
|
||||
'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 stats were successfully retrieved.', 'akismet' ),
|
||||
),
|
||||
'spam' => array(
|
||||
'type' => 'integer',
|
||||
'description' => __( 'Total number of spam comments blocked.', 'akismet' ),
|
||||
),
|
||||
'ham' => array(
|
||||
'type' => 'integer',
|
||||
'description' => __( 'Total number of legitimate comments approved.', 'akismet' ),
|
||||
),
|
||||
'missed_spam' => array(
|
||||
'type' => 'integer',
|
||||
'description' => __( 'Number of spam comments that were missed.', 'akismet' ),
|
||||
),
|
||||
'false_positives' => array(
|
||||
'type' => 'integer',
|
||||
'description' => __( 'Number of legitimate comments incorrectly marked as spam.', 'akismet' ),
|
||||
),
|
||||
'accuracy' => array(
|
||||
'type' => 'number',
|
||||
'description' => __( 'Accuracy percentage of spam detection.', 'akismet' ),
|
||||
),
|
||||
'time_saved' => array(
|
||||
'type' => 'integer',
|
||||
'description' => __( 'Estimated time saved by Akismet blocking spam, in seconds.', 'akismet' ),
|
||||
),
|
||||
'breakdown' => array(
|
||||
'type' => 'object',
|
||||
'description' => __( 'Monthly breakdown of statistics.', 'akismet' ),
|
||||
'additionalProperties' => array(
|
||||
'type' => 'object',
|
||||
'properties' => array(
|
||||
'spam' => array(
|
||||
'type' => 'integer',
|
||||
'description' => __( 'Total number of spam comments blocked in this period.', 'akismet' ),
|
||||
),
|
||||
'ham' => array(
|
||||
'type' => 'integer',
|
||||
'description' => __( 'Total number of legitimate comments approved in this period.', 'akismet' ),
|
||||
),
|
||||
'missed_spam' => array(
|
||||
'type' => 'integer',
|
||||
'description' => __( 'Number of spam comments that were missed in this period.', 'akismet' ),
|
||||
),
|
||||
'false_positives' => array(
|
||||
'type' => 'integer',
|
||||
'description' => __( 'Number of legitimate comments incorrectly marked as spam in this period.', 'akismet' ),
|
||||
),
|
||||
'da' => array(
|
||||
'type' => 'string',
|
||||
'description' => __( 'Date for this period.', 'akismet' ),
|
||||
),
|
||||
),
|
||||
),
|
||||
),
|
||||
'interval' => array(
|
||||
'type' => 'string',
|
||||
'description' => __( 'The time interval for these stats.', 'akismet' ),
|
||||
),
|
||||
'error' => array(
|
||||
'type' => 'string',
|
||||
'description' => __( 'Error message if the operation could not be completed.', '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' => true,
|
||||
),
|
||||
'mcp' => array(
|
||||
'public' => ( get_option( 'akismet_enable_mcp_access' ) === '1' ),
|
||||
'type' => 'tool',
|
||||
),
|
||||
'show_in_rest' => true,
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Execute callback for the get-stats ability.
|
||||
*
|
||||
* @param array|null $input The input parameters with optional interval.
|
||||
* @return array|WP_Error The stats data or error.
|
||||
*/
|
||||
public function execute( ?array $input = null ) {
|
||||
// Get interval from input or use default.
|
||||
$interval = isset( $input['interval'] ) ? $input['interval'] : '6-months';
|
||||
|
||||
// Fetch stats from Akismet API.
|
||||
$data = Akismet::get_stats( $interval );
|
||||
|
||||
if ( ! $data ) {
|
||||
return new WP_Error(
|
||||
'stats_fetch_failed',
|
||||
__( 'Failed to retrieve stats from Akismet API.', 'akismet' )
|
||||
);
|
||||
}
|
||||
|
||||
// Build response with data from API (already properly typed by get_stats).
|
||||
return array_merge(
|
||||
array(
|
||||
'success' => true,
|
||||
'interval' => $interval,
|
||||
),
|
||||
(array) $data
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,60 @@
|
||||
<?php
|
||||
/**
|
||||
* Represents a Base Ability.
|
||||
*
|
||||
* This class holds a default constructor to register the ability and a default permission.
|
||||
*
|
||||
* @package Akismet
|
||||
* @since 5.7
|
||||
*/
|
||||
|
||||
declare( strict_types = 1 );
|
||||
|
||||
/**
|
||||
* Base class for Akismet abilities.
|
||||
*
|
||||
* @package Akismet
|
||||
* @since 5.7
|
||||
*/
|
||||
abstract class Akismet_Ability implements Akismet_Ability_Interface {
|
||||
|
||||
/**
|
||||
* Get the ability name.
|
||||
*
|
||||
* Classes extending this must implement this method to provide the ability name into the registration.
|
||||
*
|
||||
* @return string The ability name.
|
||||
*/
|
||||
abstract protected function get_ability_name(): string;
|
||||
|
||||
/**
|
||||
* Get the config.
|
||||
*
|
||||
* Classes extending this must implement this method to provide the ability configuration into the registration.
|
||||
*
|
||||
* @return array The ability configuration array.
|
||||
*/
|
||||
abstract public function get_config(): array;
|
||||
|
||||
/**
|
||||
* Constructor - registers the ability.
|
||||
*/
|
||||
public function __construct() {
|
||||
wp_register_ability(
|
||||
$this->get_ability_name(),
|
||||
$this->get_config()
|
||||
);
|
||||
}
|
||||
|
||||
// phpcs:disable Generic.CodeAnalysis.UnusedFunctionParameter.Found -- Base class default, subclasses use $input.
|
||||
/**
|
||||
* Permission callback for any ability that uses this trait.
|
||||
*
|
||||
* @param array|null $input The input parameters (unused).
|
||||
* @return bool Whether the current user can use this ability.
|
||||
*/
|
||||
public function current_user_has_permission( ?array $input = null ): bool {
|
||||
// phpcs:enable Generic.CodeAnalysis.UnusedFunctionParameter.Found
|
||||
return current_user_can( 'moderate_comments' );
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,62 @@
|
||||
<?php
|
||||
/**
|
||||
* Interface for Akismet abilities.
|
||||
*
|
||||
* @package Akismet
|
||||
* @since 5.7
|
||||
*/
|
||||
|
||||
declare( strict_types = 1 );
|
||||
|
||||
/**
|
||||
* Interface Akismet_Ability_Interface
|
||||
*/
|
||||
interface Akismet_Ability_Interface {
|
||||
|
||||
/**
|
||||
* Get the ability configuration array.
|
||||
*
|
||||
* Returns the configuration array used to register the ability with wp_register_ability().
|
||||
*
|
||||
* @return array {
|
||||
* The ability configuration array.
|
||||
*
|
||||
* @type string $label A human-readable name for the ability. Used for display purposes. Should be translatable.
|
||||
* @type string $description A detailed description of what the ability does, its purpose, and its parameters or return values.
|
||||
* This is crucial for AI agents to understand how and when to use the ability.
|
||||
* @type string $category The slug of the category this ability belongs to. The category must be registered before
|
||||
* registering the ability.
|
||||
* @type array $output_schema A JSON Schema definition describing the expected format of the data returned by the ability.
|
||||
* Used for validation and documentation.
|
||||
* @type callable $execute_callback The PHP function or method to execute when this ability is called. Receives optional input
|
||||
* argument matching the input schema type.
|
||||
* @type callable $permission_callback A callback function to check if the current user has permission to execute this ability.
|
||||
* Returns boolean or WP_Error.
|
||||
* @type array $input_schema Optional. JSON Schema defining expected input parameters. Required when the ability accepts inputs.
|
||||
* @type array $meta Optional. An associative array for storing arbitrary additional metadata about the ability,
|
||||
* including 'annotations' (readonly, destructive, idempotent flags) and 'show_in_rest'.
|
||||
* @type string $ability_class Optional. Custom class name extending WP_Ability for behavior customization.
|
||||
* }
|
||||
*/
|
||||
public function get_config(): array;
|
||||
|
||||
/**
|
||||
* Execute callback for the ability.
|
||||
*
|
||||
* Runs the main functionality of the ability.
|
||||
*
|
||||
* @param array|null $input The input parameters for the ability. Null when no input provided.
|
||||
* @return array|WP_Error The result of the execution or a WP_Error on failure.
|
||||
*/
|
||||
public function execute( ?array $input = null );
|
||||
|
||||
/**
|
||||
* Permission callback for the ability.
|
||||
*
|
||||
* Checks if the current user has permission to execute the ability.
|
||||
*
|
||||
* @param array|null $input The input parameters for the ability. Null when no input provided.
|
||||
* @return bool Whether the current user has permission.
|
||||
*/
|
||||
public function current_user_has_permission( ?array $input = null ): bool;
|
||||
}
|
||||
Reference in New Issue
Block a user