comment_flood_trigger
comment_flood_trigger is used when a commenter "floods" WordPress with comments (tries to post two comments within 15 seconds). It can pass two parameters: the Unix timestamp of the last comment attempted, and the Unix timestamp of the currently attempted comment.
Context:
File: wp-includes/functions-post.php
// Simple flood-protection
if ( $lasttime = $wpdb->get_var("SELECT comment_date_gmt FROM $wpdb->comments WHERE comment_author_IP = '$user_ip' OR comment_author_email = '$email' ORDER BY comment_date DESC LIMIT 1") ) {
$time_lastcomment = mysql2date('U', $lasttime);
$time_newcomment = mysql2date('U', $now_gmt);
if ( ($time_newcomment - $time_lastcomment) < 15 ) {
do_action('comment_flood_trigger', $time_lastcomment, $time_newcomment);
die( __('Sorry, you can only post a new comment once every 15 seconds. Slow down cowboy.') );
}
}
This hook can pass multiple parameters. In order to get additional parameters (up to 2 for this hook) passed to your function, you will have to hook in like this: add_filter('comment_flood_trigger', 'your_function', 10, 2); where 10 is your function's priority, and 2 is the number of parameters you want your function to accept. Note that your function should only return the first parameter.
This hook is an action which means that it primarily acts as an event trigger, instead of a content filter. This is a semantic difference, but it will help you to remember what this hook does if you use it like this: add_action('comment_flood_trigger', 'your_function');