Index: src/wp-includes/comment.php =================================================================== --- src/wp-includes/comment.php (revision 26348) +++ src/wp-includes/comment.php (working copy) @@ -27,16 +27,16 @@ * @since 1.2.0 * @uses $wpdb * - * @param string $author Comment Author's name - * @param string $email Comment Author's email - * @param string $url Comment Author's URL - * @param string $comment Comment contents - * @param string $user_ip Comment Author's IP address - * @param string $user_agent Comment Author's User Agent + * @param string $author Comment Author's name. + * @param string $email Comment Author's email. + * @param string $url Comment Author's URL. + * @param string $comment Comment contents. + * @param string $user_ip Comment Author's IP address. + * @param string $user_agent Comment Author's User Agent. * @param string $comment_type Comment type, either user submitted comment, - * trackback, or pingback + * trackback, or pingback. * @return bool Whether the checks passed (true) and the comments should be - * displayed or set to moderated + * displayed or set to moderated. */ function check_comment($author, $email, $url, $comment, $user_ip, $user_agent, $comment_type) { global $wpdb; @@ -44,11 +44,27 @@ if ( 1 == get_option('comment_moderation') ) return false; // If moderation is set to manual + /** + * Filter the comment text. + * + * @since 1.2.1 + * + * @param string $comment The comment text. + */ $comment = apply_filters( 'comment_text', $comment ); // Check # of external links if ( $max_links = get_option( 'comment_max_links' ) ) { $num_links = preg_match_all( '/]*href/i', $comment, $out ); + + /** + * Filters the maximum amount of links allowed in a comment + * + * @since 3.0.0 + * + * @param int $num_links The number of links allowed. + * @param string $url Comment Author's URL. + */ $num_links = apply_filters( 'comment_max_links_url', $num_links, $url ); // provide for counting of $url as a link if ( $num_links >= $max_links ) return false; @@ -102,7 +118,7 @@ * @since 2.0.0 * @uses $wpdb * - * @param int $post_id The ID of the post + * @param int $post_id The ID of the post. * @return array $comments The approved comments */ function get_approved_comments($post_id) { @@ -147,6 +163,13 @@ } } + /** + * Fires after a comment is retrieved. + * + * @since 2.3.0 + * + * @param mixed $_comment Comment data. + */ $_comment = apply_filters('get_comment', $_comment); if ( $output == OBJECT ) { @@ -188,7 +211,7 @@ */ class WP_Comment_Query { /** - * Metadata query container + * Metadata query container. * * @since 3.5.0 * @access public @@ -197,7 +220,7 @@ var $meta_query = false; /** - * Date query container + * Date query container. * * @since 3.7.0 * @access public @@ -206,11 +229,11 @@ var $date_query = false; /** - * Execute the query + * Execute the query. * * @since 3.1.0 * - * @param string|array $query_vars + * @param string|array $query_vars. * @return int|array */ function query( $query_vars ) { @@ -251,6 +274,13 @@ $this->meta_query = new WP_Meta_Query(); $this->meta_query->parse_query_vars( $this->query_vars ); + /** + * Fires before comments are retrieved. + * + * @since 3.1.0 + * + * @param WP_Comment_Query Current instance of WP_Comment_Query. + */ do_action_ref_array( 'pre_get_comments', array( &$this ) ); extract( $this->query_vars, EXTR_SKIP ); @@ -376,6 +406,15 @@ } $pieces = array( 'fields', 'join', 'where', 'orderby', 'order', 'limits', 'groupby' ); + + /** + * Filter the comments clauses + * + * @since 3.1.0 + * + * @param array An array containing all the pieces. + * @param WP_Comment_Query Current instance of WP_Comment_Query. + */ $clauses = apply_filters_ref_array( 'comments_clauses', array( compact( $pieces ), &$this ) ); foreach ( $pieces as $piece ) $$piece = isset( $clauses[ $piece ] ) ? $clauses[ $piece ] : ''; @@ -389,6 +428,15 @@ return $wpdb->get_var( $query ); $comments = $wpdb->get_results( $query ); + + /** + * Filter the comment query results. + * + * @since 3.1.0 + * + * @param array An array containing the comments. + * @param WP_Comment_Query Current instance of WP_Comment_Query. + */ $comments = apply_filters_ref_array( 'the_comments', array( $comments, &$this ) ); wp_cache_add( $cache_key, $comments, 'comment' ); @@ -397,7 +445,7 @@ } /** - * Used internally to generate an SQL string for searching across multiple columns + * Used internally to generate an SQL string for searching across multiple columns. * * @access protected * @since 3.1.0 @@ -568,7 +616,7 @@ * @uses delete_metadata * @link http://codex.wordpress.org/Function_Reference/delete_comment_meta * - * @param int $comment_id comment ID + * @param int $comment_id comment ID. * @param string $meta_key Metadata name. * @param mixed $meta_value Optional. Metadata value. * @return bool True on success, false on failure. @@ -629,6 +677,13 @@ if ( $user->exists() ) return; + /** + * Filter the lifetime of the comment cookie. + * + * @since 2.8.0 + * + * @param int $seconds Comment cookie lifetime. Default is 30000000 seconds (ca. 347 days). + */ $comment_cookie_lifetime = apply_filters('comment_cookie_lifetime', 30000000); setcookie('comment_author_' . COOKIEHASH, $comment->comment_author, time() + $comment_cookie_lifetime, COOKIEPATH, COOKIE_DOMAIN); setcookie('comment_author_email_' . COOKIEHASH, $comment->comment_author_email, time() + $comment_cookie_lifetime, COOKIEPATH, COOKIE_DOMAIN); @@ -636,7 +691,7 @@ } /** - * Sanitizes the cookies sent to the user already. + * Sanitize the cookies sent to the user already. * * Will only do anything if the cookies have already been created for the user. * Mostly used after cookies had been sent to use elsewhere. @@ -645,6 +700,13 @@ */ function sanitize_comment_cookies() { if ( isset($_COOKIE['comment_author_'.COOKIEHASH]) ) { + /** + * Filter the comment author's name cookie before it is set. + * + * @since 2.1.0 + * + * @param string $author_cookie The comment author name. + */ $comment_author = apply_filters('pre_comment_author_name', $_COOKIE['comment_author_'.COOKIEHASH]); $comment_author = wp_unslash($comment_author); $comment_author = esc_attr($comment_author); @@ -652,6 +714,13 @@ } if ( isset($_COOKIE['comment_author_email_'.COOKIEHASH]) ) { + /** + * Filter the comment author's email cookie before it is set. + * + * @since 2.8.0 + * + * @param string $author_email_cookie The comment author email. + */ $comment_author_email = apply_filters('pre_comment_author_email', $_COOKIE['comment_author_email_'.COOKIEHASH]); $comment_author_email = wp_unslash($comment_author_email); $comment_author_email = esc_attr($comment_author_email); @@ -659,6 +728,13 @@ } if ( isset($_COOKIE['comment_author_url_'.COOKIEHASH]) ) { + /** + * Filter the comment author's URL cookie before it is set. + * + * @since 2.1.0 + * + * @param string $author_url_cookie The comment author URL. + */ $comment_author_url = apply_filters('pre_comment_author_url', $_COOKIE['comment_author_url_'.COOKIEHASH]); $comment_author_url = wp_unslash($comment_author_url); $_COOKIE['comment_author_url_'.COOKIEHASH] = $comment_author_url; @@ -674,7 +750,7 @@ * @uses apply_filters() Calls 'comment_duplicate_trigger' hook on commentdata. * @uses do_action() Calls 'check_comment_flood' hook on $comment_author_IP, $comment_author_email, and $comment_date_gmt * - * @param array $commentdata Contains information on the comment + * @param array $commentdata Contains information on the comment. * @return mixed Signifies the approval status (0|1|'spam') */ function wp_allow_comment($commentdata) { @@ -688,6 +764,13 @@ $dupe .= $wpdb->prepare( "OR comment_author_email = %s ", wp_unslash( $comment_author_email ) ); $dupe .= $wpdb->prepare( ") AND comment_content = %s LIMIT 1", wp_unslash( $comment_content ) ); if ( $wpdb->get_var($dupe) ) { + /** + * Fires when a duplicate comment is detected. + * + * @since 3.0.0 + * + * @param array $commentdata Comment data. + */ do_action( 'comment_duplicate_trigger', $commentdata ); if ( defined('DOING_AJAX') ) die( __('Duplicate comment detected; it looks as though you’ve already said that!') ); @@ -695,6 +778,17 @@ wp_die( __('Duplicate comment detected; it looks as though you’ve already said that!') ); } + /** + * Fires before a comment gets approved. + * + * Allows for checking of comment flooding. + * + * @since 2.3.0 + * + * @param string $comment_author_IP The comment author's IP address + * @param string $comment_author_email The comment author's email + * @param string $comment_date_gmt The date the comment was posted in GMT + */ do_action( 'check_comment_flood', $comment_author_IP, $comment_author_email, $comment_date_gmt ); if ( ! empty( $user_id ) ) { @@ -705,7 +799,7 @@ if ( isset( $user ) && ( $user_id == $post_author || $user->has_cap( 'moderate_comments' ) ) ) { // The author and the admins get respect. $approved = 1; - } else { + } else { // Everyone else's comments will be checked. if ( check_comment($comment_author, $comment_author_email, $comment_author_url, $comment_content, $comment_author_IP, $comment_agent, $comment_type) ) $approved = 1; @@ -715,6 +809,14 @@ $approved = 'spam'; } + /** + * Filter the comment's approval status before it is set. + * + * @since 2.1.0 + * + * @param int|string $approved The approval status. Default is either 1, 0 or 'spam'. + * @param array $commentdata Comment data. + */ $approved = apply_filters( 'pre_comment_approved', $approved, $commentdata ); return $approved; } @@ -744,8 +846,25 @@ if ( $lasttime = $wpdb->get_var( $wpdb->prepare( "SELECT `comment_date_gmt` FROM `$wpdb->comments` WHERE `comment_date_gmt` >= %s AND ( `comment_author_IP` = %s OR `comment_author_email` = %s ) ORDER BY `comment_date_gmt` DESC LIMIT 1", $hour_ago, $ip, $email ) ) ) { $time_lastcomment = mysql2date('U', $lasttime, false); $time_newcomment = mysql2date('U', $date, false); + /** + * Filter the comment flood variable. + * + * @since 2.1.0 + * + * @param bool $bool True if comment flooding is happening, false if not. Default is false. + * @param string $time_lastcomment Time when the last comment was posted. + * @param string $time_newcomment Time when the new comment was posted. + */ $flood_die = apply_filters('comment_flood_filter', false, $time_lastcomment, $time_newcomment); if ( $flood_die ) { + /** + * Fires before comment flooding message is triggered + * + * @since 2.1.0 + * + * @param string $time_lastcomment Time when the last comment was posted + * @param string $time_newcomment Time when the new comment was posted + */ do_action('comment_flood_trigger', $time_lastcomment, $time_newcomment); if ( defined('DOING_AJAX') ) @@ -893,15 +1012,27 @@ * @since 1.5.0 * @uses do_action() Calls 'wp_blacklist_check' hook for all parameters. * - * @param string $author The author of the comment - * @param string $email The email of the comment - * @param string $url The url used in the comment - * @param string $comment The comment content - * @param string $user_ip The comment author IP address - * @param string $user_agent The author's browser user agent + * @param string $author The author of the comment. + * @param string $email The email of the comment. + * @param string $url The url used in the comment. + * @param string $comment The comment content. + * @param string $user_ip The comment author IP address. + * @param string $user_agent The author's browser user agent. * @return bool True if comment contains blacklisted content, false if comment does not */ function wp_blacklist_check($author, $email, $url, $comment, $user_ip, $user_agent) { + /** + * Fires before the comment is tested for blacklisted characters or words. + * + * @since 1.5.0 + * + * @param string $author The author of the comment + * @param string $email The email of the comment + * @param string $url The url used in the comment + * @param string $comment The comment content + * @param string $user_ip The comment author IP address + * @param string $user_agent The author's browser user agent + */ do_action('wp_blacklist_check', $author, $email, $url, $comment, $user_ip, $user_agent); $mod_keys = trim( get_option('blacklist_keys') ); @@ -921,13 +1052,13 @@ $pattern = "#$word#i"; if ( - preg_match($pattern, $author) + preg_match($pattern, $author) || preg_match($pattern, $email) || preg_match($pattern, $url) || preg_match($pattern, $comment) || preg_match($pattern, $user_ip) || preg_match($pattern, $user_agent) - ) + ) return true; } return false; @@ -954,6 +1085,14 @@ $post_id = (int) $post_id; + /** + * Filter the comments count for the given post. + * + * @since + * + * @param array $count An empty array. + * @param int $post_id Post ID. + */ $stats = apply_filters('wp_count_comments', array(), $post_id); if ( !empty($stats) ) return $stats; @@ -1007,7 +1146,7 @@ * @uses do_action() Calls 'wp_set_comment_status' hook on comment ID with 'delete' set for the second parameter * @uses wp_transition_comment_status() Passes new and old comment status along with $comment object * - * @param int $comment_id Comment ID + * @param int $comment_id Comment ID. * @param bool $force_delete Whether to bypass trash and force deletion. Default is false. * @return bool True on success, false on failure. */ @@ -1019,6 +1158,13 @@ if ( !$force_delete && EMPTY_TRASH_DAYS && !in_array( wp_get_comment_status($comment_id), array( 'trash', 'spam' ) ) ) return wp_trash_comment($comment_id); + /** + * Fires before a comment is deleted. + * + * @since 2.1.0 + * + * @param int $comment_id Comment ID. + */ do_action('delete_comment', $comment_id); // Move children up a level. @@ -1035,6 +1181,14 @@ if ( ! $wpdb->delete( $wpdb->comments, array( 'comment_ID' => $comment_id ) ) ) return false; + + /** + * Fires after comment metadata has been deleted. + * + * @since 2.9.0 + * + * @param int $comment_id Comment ID. + */ do_action('deleted_comment', $comment_id); $post_id = $comment->comment_post_ID; @@ -1043,13 +1197,21 @@ clean_comment_cache($comment_id); + /** + * Fires before transitioning the comment's status to 'delete'. + * + * @since 2.1.0 + * + * @param int $comment_id Comment ID. + * @param string $status The new status 'delete'. + */ do_action('wp_set_comment_status', $comment_id, 'delete'); wp_transition_comment_status('delete', $comment->comment_approved, $comment); return true; } /** - * Moves a comment to the Trash + * Moves a comment to the Trash. * * If trash is disabled, comment is permanently deleted. * @@ -1068,11 +1230,26 @@ if ( !$comment = get_comment($comment_id) ) return false; + /** + * Fires before a comment is sent to the trash. + * + * @since 2.9.0 + * + * @param int $comment_id Comment ID. + */ do_action('trash_comment', $comment_id); if ( wp_set_comment_status($comment_id, 'trash') ) { add_comment_meta($comment_id, '_wp_trash_meta_status', $comment->comment_approved); add_comment_meta($comment_id, '_wp_trash_meta_time', time() ); + + /** + * Fires after a comment is sent to the trash. + * + * @since 2.9.0 + * + * @param int $comment_id Comment ID. + */ do_action('trashed_comment', $comment_id); return true; } @@ -1081,7 +1258,7 @@ } /** - * Removes a comment from the Trash + * Removes a comment from the Trash. * * @since 2.9.0 * @uses do_action() on 'untrash_comment' before untrashing @@ -1094,6 +1271,13 @@ if ( ! (int)$comment_id ) return false; + /** + * Fires before a comment is restored from the trash. + * + * @since 2.9.0 + * + * @param int $comment_id Comment ID. + */ do_action('untrash_comment', $comment_id); $status = (string) get_comment_meta($comment_id, '_wp_trash_meta_status', true); @@ -1103,6 +1287,13 @@ if ( wp_set_comment_status($comment_id, $status) ) { delete_comment_meta($comment_id, '_wp_trash_meta_time'); delete_comment_meta($comment_id, '_wp_trash_meta_status'); + /** + * Fires after a comment is restored from the trash. + * + * @since 2.9.0 + * + * @param int $comment_id Comment ID. + */ do_action('untrashed_comment', $comment_id); return true; } @@ -1111,7 +1302,7 @@ } /** - * Marks a comment as Spam + * Marks a comment as Spam. * * @since 2.9.0 * @uses do_action() on 'spam_comment' before spamming @@ -1124,10 +1315,24 @@ if ( !$comment = get_comment($comment_id) ) return false; + /** + * Fires before a comment is marked as spam. + * + * @since 2.9.0 + * + * @param int $comment_id Comment ID. + */ do_action('spam_comment', $comment_id); if ( wp_set_comment_status($comment_id, 'spam') ) { add_comment_meta($comment_id, '_wp_trash_meta_status', $comment->comment_approved); + /** + * Fires after a comment is marked as spam. + * + * @since 2.9.0 + * + * @param int $comment_id Comment ID. + */ do_action('spammed_comment', $comment_id); return true; } @@ -1136,7 +1341,7 @@ } /** - * Removes a comment from the Spam + * Fires before a comment is un-marked as Spam. * * @since 2.9.0 * @uses do_action() on 'unspam_comment' before unspamming @@ -1149,6 +1354,13 @@ if ( ! (int)$comment_id ) return false; + /** + * Fires after a comment is un-marked as Spam. + * + * @since 2.9.0 + * + * @param int $comment_id Comment ID. + */ do_action('unspam_comment', $comment_id); $status = (string) get_comment_meta($comment_id, '_wp_trash_meta_status', true); @@ -1157,6 +1369,14 @@ if ( wp_set_comment_status($comment_id, $status) ) { delete_comment_meta($comment_id, '_wp_trash_meta_status'); + + /** + * Fires after a comment is removed from the Spam. + * + * @since 2.9.0 + * + * @param int $comment_id Comment ID. + */ do_action('unspammed_comment', $comment_id); return true; } @@ -1169,7 +1389,7 @@ * * @since 1.0.0 * - * @param int $comment_id Comment ID + * @param int $comment_id Comment ID. * @return string|bool Status might be 'trash', 'approved', 'unapproved', 'spam'. False on failure. */ function wp_get_comment_status($comment_id) { @@ -1305,6 +1525,15 @@ wp_update_comment_count($comment_post_ID); $comment = get_comment($id); + + /** + * Fires after the comment is inserted. + * + * @since + * + * @param int $id Comment ID. + * @param object $comment Comment object. + */ do_action('wp_insert_comment', $id, $comment); wp_cache_set( 'last_changed', microtime(), 'comment' ); @@ -1313,7 +1542,7 @@ } /** - * Filters and sanitizes comment data. + * Filter and sanitize comment data. * * Sets the comment data 'filtered' field to true when finished. This can be * checked as to whether the comment should be filtered and to keep from @@ -1367,7 +1596,7 @@ /** * Adds a new comment to the database. * - * Filters new comment to ensure that the fields are sanitized and valid before + * Filter new comment to ensure that the fields are sanitized and valid before * inserting comment into database. Calls 'comment_post' action with comment ID * and whether comment is approved by WordPress. Also has 'preprocess_comment' * filter for processing the comment data before the function handles it. @@ -1491,7 +1720,7 @@ /** * Updates an existing comment in the database. * - * Filters the comment and makes sure certain fields are valid before updating. + * Filter the comment and makes sure certain fields are valid before updating. * * @since 2.0.0 * @uses $wpdb @@ -1584,8 +1813,8 @@ * @since 2.1.0 * @see wp_update_comment_count_now() For what could cause a false return value * - * @param int $post_id Post ID - * @param bool $do_deferred Whether to process previously deferred post comment counts + * @param int $post_id Post ID. + * @param bool $do_deferred Whether to process previously deferred post comment counts. * @return bool True on success, false on failure */ function wp_update_comment_count($post_id, $do_deferred=false) { @@ -1617,7 +1846,7 @@ * @uses do_action() Calls 'wp_update_comment_count' hook on $post_id, $new, and $old * @uses do_action() Calls 'edit_posts' hook on $post_id and $post * - * @param int $post_id Post ID + * @param int $post_id Post ID. * @return bool True on success, false on '0' $post_id or if post with ID does not exist. */ function wp_update_comment_count_now($post_id) { @@ -1863,7 +2092,7 @@ if ( $pingback_server_url ) { @ set_time_limit( 60 ); - // Now, the RPC call + // Now, the RPC call $pagelinkedfrom = get_permalink($post_ID); // using a timeout of 3 seconds should be enough to cover slow servers @@ -1960,7 +2189,7 @@ } /** - * Default filter attached to pingback_ping_source_uri to validate the pingback's Source URI + * Default filter attached to pingback_ping_source_uri to validate the pingback's Source URI. * * @since 3.5.1 * @see wp_http_validate_url() @@ -2001,7 +2230,7 @@ * @package WordPress * @subpackage Cache * - * @param int|array $ids Comment ID or array of comment IDs to remove from cache + * @param int|array $ids Comment ID or array of comment IDs to remove from cache. */ function clean_comment_cache($ids) { foreach ( (array) $ids as $id ) @@ -2021,7 +2250,7 @@ * @package WordPress * @subpackage Cache * - * @param array $comments Array of comment row objects + * @param array $comments Array of comment row objects. */ function update_comment_cache($comments) { foreach ( (array) $comments as $comment ) @@ -2046,6 +2275,13 @@ if ( empty( $posts ) || ! $query->is_singular() || ! get_option( 'close_comments_for_old_posts' ) ) return $posts; + /** + * Filter the post types on which old comments should be closed automatically. + * + * @since 3.2.0 + * + * @param array $post_types An array of registered post types. + */ $post_types = apply_filters( 'close_comments_for_post_types', array( 'post' ) ); if ( ! in_array( $posts[0]->post_type, $post_types ) ) return $posts; @@ -2068,8 +2304,8 @@ * @access private * @since 2.7.0 * - * @param bool $open Comments open or closed - * @param int $post_id Post ID + * @param bool $open Comments open or closed. + * @param int $post_id Post ID. * @return bool $open */ function _close_comments_for_old_post( $open, $post_id ) { @@ -2085,6 +2321,7 @@ $post = get_post($post_id); + /** This filter is documented in wp-includes/comment.php */ $post_types = apply_filters( 'close_comments_for_post_types', array( 'post' ) ); if ( ! in_array( $post->post_type, $post_types ) ) return $open;