WordPress.org

Make WordPress Core

Ticket #25522: 25522.5.diff

File 25522.5.diff, 30.1 KB (added by DrewAPicture, 8 years ago)

Final tweaks

  • src/wp-includes/comment.php

     
    4444        if ( 1 == get_option('comment_moderation') )
    4545                return false; // If moderation is set to manual
    4646
     47        /** This filter is documented in wp-includes/comment-template.php */
    4748        $comment = apply_filters( 'comment_text', $comment );
    4849
    4950        // Check # of external links
    5051        if ( $max_links = get_option( 'comment_max_links' ) ) {
    5152                $num_links = preg_match_all( '/<a [^>]*href/i', $comment, $out );
    52                 $num_links = apply_filters( 'comment_max_links_url', $num_links, $url ); // provide for counting of $url as a link
     53                /**
     54                 * Filter the maximum number of links allowed in a comment.
     55                 *
     56                 * @since 3.0.0
     57                 *
     58                 * @param int    $num_links The number of links allowed.
     59                 * @param string $url       Comment author's URL. Included in allowed links total.
     60                 */
     61                $num_links = apply_filters( 'comment_max_links_url', $num_links, $url );
    5362                if ( $num_links >= $max_links )
    5463                        return false;
    5564        }
     
    147156                }
    148157        }
    149158
    150         $_comment = apply_filters('get_comment', $_comment);
     159        /**
     160         * Fires after a comment is retrieved.
     161         *
     162         * @since 2.3.0
     163         *
     164         * @param mixed $_comment Comment data.
     165         */
     166        $_comment = apply_filters( 'get_comment', $_comment );
    151167
    152168        if ( $output == OBJECT ) {
    153169                return $_comment;
     
    251267                $this->meta_query = new WP_Meta_Query();
    252268                $this->meta_query->parse_query_vars( $this->query_vars );
    253269
     270                /**
     271                 * Fires before comments are retrieved.
     272                 *
     273                 * @since 3.1.0
     274                 *
     275                 * @param WP_Comment_Query &$this Current instance of WP_Comment_Query, passed by reference.
     276                 */
    254277                do_action_ref_array( 'pre_get_comments', array( &$this ) );
    255278                extract( $this->query_vars, EXTR_SKIP );
    256279
     
    376399                }
    377400
    378401                $pieces = array( 'fields', 'join', 'where', 'orderby', 'order', 'limits', 'groupby' );
     402                /**
     403                 * Filter the comment query clauses.
     404                 *
     405                 * @since 3.1.0
     406                 *
     407                 * @param array            $pieces A compacted array of comment query clauses.
     408                 * @param WP_Comment_Query &$this  Current instance of WP_Comment_Query, passed by reference.
     409                 */
    379410                $clauses = apply_filters_ref_array( 'comments_clauses', array( compact( $pieces ), &$this ) );
    380411                foreach ( $pieces as $piece )
    381412                        $$piece = isset( $clauses[ $piece ] ) ? $clauses[ $piece ] : '';
     
    389420                        return $wpdb->get_var( $query );
    390421
    391422                $comments = $wpdb->get_results( $query );
     423                /**
     424                 * Filter the comment query results.
     425                 *
     426                 * @since 3.1.0
     427                 *
     428                 * @param array            $comments An array of comments.
     429                 * @param WP_Comment_Query &$this    Current instance of WP_Comment_Query, passed by reference.
     430                 */
    392431                $comments = apply_filters_ref_array( 'the_comments', array( $comments, &$this ) );
    393432
    394433                wp_cache_add( $cache_key, $comments, 'comment' );
     
    629668        if ( $user->exists() )
    630669                return;
    631670
    632         $comment_cookie_lifetime = apply_filters('comment_cookie_lifetime', 30000000);
     671        /**
     672         * Filter the lifetime of the comment cookie in seconds.
     673         *
     674         * @since 2.8.0
     675         *
     676         * @param int $seconds Comment cookie lifetime. Default 30000000.
     677         */
     678        $comment_cookie_lifetime = apply_filters( 'comment_cookie_lifetime', 30000000 );
    633679        setcookie('comment_author_' . COOKIEHASH, $comment->comment_author, time() + $comment_cookie_lifetime, COOKIEPATH, COOKIE_DOMAIN);
    634680        setcookie('comment_author_email_' . COOKIEHASH, $comment->comment_author_email, time() + $comment_cookie_lifetime, COOKIEPATH, COOKIE_DOMAIN);
    635681        setcookie('comment_author_url_' . COOKIEHASH, esc_url($comment->comment_author_url), time() + $comment_cookie_lifetime, COOKIEPATH, COOKIE_DOMAIN);
     
    644690 * @since 2.0.4
    645691 */
    646692function sanitize_comment_cookies() {
    647         if ( isset($_COOKIE['comment_author_'.COOKIEHASH]) ) {
    648                 $comment_author = apply_filters('pre_comment_author_name', $_COOKIE['comment_author_'.COOKIEHASH]);
     693        if ( isset( $_COOKIE['comment_author_' . COOKIEHASH] ) ) {
     694                /**
     695                 * Filter the comment author's name cookie before it is set.
     696                 *
     697                 * When this filter hook is evaluated in wp_filter_comment(),
     698                 * the comment author's name string is passed.
     699                 *
     700                 * @since 1.5.2
     701                 *
     702                 * @param string $author_cookie The comment author name cookie.
     703                 */
     704                $comment_author = apply_filters( 'pre_comment_author_name', $_COOKIE['comment_author_' . COOKIEHASH] );
    649705                $comment_author = wp_unslash($comment_author);
    650706                $comment_author = esc_attr($comment_author);
    651                 $_COOKIE['comment_author_'.COOKIEHASH] = $comment_author;
     707                $_COOKIE['comment_author_' . COOKIEHASH] = $comment_author;
    652708        }
    653709
    654         if ( isset($_COOKIE['comment_author_email_'.COOKIEHASH]) ) {
    655                 $comment_author_email = apply_filters('pre_comment_author_email', $_COOKIE['comment_author_email_'.COOKIEHASH]);
     710        if ( isset( $_COOKIE['comment_author_email_' . COOKIEHASH] ) ) {
     711                /**
     712                 * Filter the comment author's email cookie before it is set.
     713                 *
     714                 * When this filter hook is evaluated in wp_filter_comment(),
     715                 * the comment author's email string is passed.
     716                 *
     717                 * @since 1.5.2
     718                 *
     719                 * @param string $author_email_cookie The comment author email cookie.
     720                 */
     721                $comment_author_email = apply_filters( 'pre_comment_author_email', $_COOKIE['comment_author_email_' . COOKIEHASH] );
    656722                $comment_author_email = wp_unslash($comment_author_email);
    657723                $comment_author_email = esc_attr($comment_author_email);
    658724                $_COOKIE['comment_author_email_'.COOKIEHASH] = $comment_author_email;
    659725        }
    660726
    661         if ( isset($_COOKIE['comment_author_url_'.COOKIEHASH]) ) {
    662                 $comment_author_url = apply_filters('pre_comment_author_url', $_COOKIE['comment_author_url_'.COOKIEHASH]);
     727        if ( isset( $_COOKIE['comment_author_url_' . COOKIEHASH] ) ) {
     728                /**
     729                 * Filter the comment author's URL cookie before it is set.
     730                 *
     731                 * When this filter hook is evaluated in wp_filter_comment(),
     732                 * the comment author's URL string is passed.
     733                 *
     734                 * @since 1.5.2
     735                 *
     736                 * @param string $author_url_cookie The comment author URL cookie.
     737                 */
     738                $comment_author_url = apply_filters( 'pre_comment_author_url', $_COOKIE['comment_author_url_' . COOKIEHASH] );
    663739                $comment_author_url = wp_unslash($comment_author_url);
    664740                $_COOKIE['comment_author_url_'.COOKIEHASH] = $comment_author_url;
    665741        }
     
    688764                $dupe .= $wpdb->prepare( "OR comment_author_email = %s ", wp_unslash( $comment_author_email ) );
    689765        $dupe .= $wpdb->prepare( ") AND comment_content = %s LIMIT 1", wp_unslash( $comment_content ) );
    690766        if ( $wpdb->get_var($dupe) ) {
     767                /**
     768                 * Fires immediately after a duplicate comment is detected.
     769                 *
     770                 * @since 3.0.0
     771                 *
     772                 * @param array $commentdata Comment data.
     773                 */
    691774                do_action( 'comment_duplicate_trigger', $commentdata );
    692775                if ( defined('DOING_AJAX') )
    693776                        die( __('Duplicate comment detected; it looks as though you&#8217;ve already said that!') );
     
    695778                wp_die( __('Duplicate comment detected; it looks as though you&#8217;ve already said that!') );
    696779        }
    697780
     781        /**
     782         * Fires immediately before a comment is marked approved.
     783         *
     784         * Allows checking for comment flooding.
     785         *
     786         * @since 2.3.0
     787         *
     788         * @param string $comment_author_IP    Comment author's IP address.
     789         * @param string $comment_author_email Comment author's email.
     790         * @param string $comment_date_gmt     GMT date the comment was posted.
     791         */
    698792        do_action( 'check_comment_flood', $comment_author_IP, $comment_author_email, $comment_date_gmt );
    699793
    700794        if ( ! empty( $user_id ) ) {
     
    705799        if ( isset( $user ) && ( $user_id == $post_author || $user->has_cap( 'moderate_comments' ) ) ) {
    706800                // The author and the admins get respect.
    707801                $approved = 1;
    708          } else {
     802        } else {
    709803                // Everyone else's comments will be checked.
    710804                if ( check_comment($comment_author, $comment_author_email, $comment_author_url, $comment_content, $comment_author_IP, $comment_agent, $comment_type) )
    711805                        $approved = 1;
     
    715809                        $approved = 'spam';
    716810        }
    717811
     812        /**
     813         * Filter a comment's approval status before it is set.
     814         *
     815         * @since 2.1.0
     816         *
     817         * @param bool|string $approved    The approval status. Accepts 1, 0, or 'spam'.
     818         * @param array       $commentdata Comment data.
     819         */
    718820        $approved = apply_filters( 'pre_comment_approved', $approved, $commentdata );
    719821        return $approved;
    720822}
     
    744846        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 ) ) ) {
    745847                $time_lastcomment = mysql2date('U', $lasttime, false);
    746848                $time_newcomment  = mysql2date('U', $date, false);
    747                 $flood_die = apply_filters('comment_flood_filter', false, $time_lastcomment, $time_newcomment);
     849                /**
     850                 * Filter the comment flood status.
     851                 *
     852                 * @since 2.1.0
     853                 *
     854                 * @param bool $bool             Whether a comment flood is occurring. Default false.
     855                 * @param int  $time_lastcomment Timestamp of when the last comment was posted.
     856                 * @param int  $time_newcomment  Timestamp of when the new comment was posted.
     857                 */
     858                $flood_die = apply_filters( 'comment_flood_filter', false, $time_lastcomment, $time_newcomment );
    748859                if ( $flood_die ) {
    749                         do_action('comment_flood_trigger', $time_lastcomment, $time_newcomment);
     860                        /**
     861                         * Fires before the comment flood message is triggered.
     862                         *
     863                         * @since 1.5.2
     864                         *
     865                         * @param int $time_lastcomment Timestamp of when the last comment was posted.
     866                         * @param int $time_newcomment  Timestamp of when the new comment was posted.
     867                         */
     868                        do_action( 'comment_flood_trigger', $time_lastcomment, $time_newcomment );
    750869
    751870                        if ( defined('DOING_AJAX') )
    752871                                die( __('You are posting comments too quickly. Slow down.') );
     
    9021021 * @return bool True if comment contains blacklisted content, false if comment does not
    9031022 */
    9041023function wp_blacklist_check($author, $email, $url, $comment, $user_ip, $user_agent) {
    905         do_action('wp_blacklist_check', $author, $email, $url, $comment, $user_ip, $user_agent);
     1024        /**
     1025         * Fires before the comment is tested for blacklisted characters or words.
     1026         *
     1027         * @since 1.5.2
     1028         *
     1029         * @param string $author     Comment author.
     1030         * @param string $email      Comment author's email.
     1031         * @param string $url        Comment author's URL.
     1032         * @param string $comment    Comment content.
     1033         * @param string $user_ip    Comment author's IP address.
     1034         * @param string $user_agent Comment author's browser user agent.
     1035         */
     1036        do_action( 'wp_blacklist_check', $author, $email, $url, $comment, $user_ip, $user_agent );
    9061037
    9071038        $mod_keys = trim( get_option('blacklist_keys') );
    9081039        if ( '' == $mod_keys )
     
    9541085
    9551086        $post_id = (int) $post_id;
    9561087
    957         $stats = apply_filters('wp_count_comments', array(), $post_id);
     1088        /**
     1089         * Filter the comments count for a given post.
     1090         *
     1091         * @since 2.7.0
     1092         *
     1093         * @param array $count   An empty array.
     1094         * @param int   $post_id The post ID.
     1095         */
     1096        $stats = apply_filters( 'wp_count_comments', array(), $post_id );
    9581097        if ( !empty($stats) )
    9591098                return $stats;
    9601099
     
    10191158        if ( !$force_delete && EMPTY_TRASH_DAYS && !in_array( wp_get_comment_status($comment_id), array( 'trash', 'spam' ) ) )
    10201159                return wp_trash_comment($comment_id);
    10211160
    1022         do_action('delete_comment', $comment_id);
     1161        /**
     1162         * Fires immediately before a comment is deleted from the database.
     1163         *
     1164         * @since 1.2.1
     1165         *
     1166         * @param int $comment_id The comment ID.
     1167         */
     1168        do_action( 'delete_comment', $comment_id );
    10231169
    10241170        // Move children up a level.
    10251171        $children = $wpdb->get_col( $wpdb->prepare("SELECT comment_ID FROM $wpdb->comments WHERE comment_parent = %d", $comment_id) );
     
    10351181
    10361182        if ( ! $wpdb->delete( $wpdb->comments, array( 'comment_ID' => $comment_id ) ) )
    10371183                return false;
    1038         do_action('deleted_comment', $comment_id);
    10391184
     1185        /**
     1186         * Fires immediately after a comment is deleted from the database.
     1187         *
     1188         * @since 2.9.0
     1189         *
     1190         * @param int $comment_id The comment ID.
     1191         */
     1192        do_action( 'deleted_comment', $comment_id );
     1193
    10401194        $post_id = $comment->comment_post_ID;
    10411195        if ( $post_id && $comment->comment_approved == 1 )
    10421196                wp_update_comment_count($post_id);
    10431197
    10441198        clean_comment_cache($comment_id);
    10451199
    1046         do_action('wp_set_comment_status', $comment_id, 'delete');
     1200        /**
     1201         * Fires immediately before changing the comment's status to 'delete'.
     1202         *
     1203         * @since 1.5.2
     1204         *
     1205         * @param int    $comment_id The comment ID.
     1206         * @param string $status     The new 'delete' comment status.
     1207         */
     1208        do_action( 'wp_set_comment_status', $comment_id, 'delete' );
    10471209        wp_transition_comment_status('delete', $comment->comment_approved, $comment);
    10481210        return true;
    10491211}
     
    10681230        if ( !$comment = get_comment($comment_id) )
    10691231                return false;
    10701232
    1071         do_action('trash_comment', $comment_id);
     1233        /**
     1234         * Fires immediately before a comment is sent to the Trash.
     1235         *
     1236         * @since 2.9.0
     1237         *
     1238         * @param int $comment_id The comment ID.
     1239         */
     1240        do_action( 'trash_comment', $comment_id );
    10721241
    10731242        if ( wp_set_comment_status($comment_id, 'trash') ) {
    10741243                add_comment_meta($comment_id, '_wp_trash_meta_status', $comment->comment_approved);
    10751244                add_comment_meta($comment_id, '_wp_trash_meta_time', time() );
    1076                 do_action('trashed_comment', $comment_id);
     1245
     1246                /**
     1247                 * Fires immediately after a comment is sent to Trash.
     1248                 *
     1249                 * @since 2.9.0
     1250                 *
     1251                 * @param int $comment_id The comment ID.
     1252                 */
     1253                do_action( 'trashed_comment', $comment_id );
    10771254                return true;
    10781255        }
    10791256
     
    10941271        if ( ! (int)$comment_id )
    10951272                return false;
    10961273
    1097         do_action('untrash_comment', $comment_id);
     1274        /**
     1275         * Fires immediately before a comment is restored from the Trash.
     1276         *
     1277         * @since 2.9.0
     1278         *
     1279         * @param int $comment_id The comment ID.
     1280         */
     1281        do_action( 'untrash_comment', $comment_id );
    10981282
    10991283        $status = (string) get_comment_meta($comment_id, '_wp_trash_meta_status', true);
    11001284        if ( empty($status) )
     
    11031287        if ( wp_set_comment_status($comment_id, $status) ) {
    11041288                delete_comment_meta($comment_id, '_wp_trash_meta_time');
    11051289                delete_comment_meta($comment_id, '_wp_trash_meta_status');
    1106                 do_action('untrashed_comment', $comment_id);
     1290                /**
     1291                 * Fires immediately after a comment is restored from the Trash.
     1292                 *
     1293                 * @since 2.9.0
     1294                 *
     1295                 * @param int $comment_id The comment ID.
     1296                 */
     1297                do_action( 'untrashed_comment', $comment_id );
    11071298                return true;
    11081299        }
    11091300
     
    11241315        if ( !$comment = get_comment($comment_id) )
    11251316                return false;
    11261317
    1127         do_action('spam_comment', $comment_id);
     1318        /**
     1319         * Fires immediately before a comment is marked as Spam.
     1320         *
     1321         * @since 2.9.0
     1322         *
     1323         * @param int $comment_id The comment ID.
     1324         */
     1325        do_action( 'spam_comment', $comment_id );
    11281326
    11291327        if ( wp_set_comment_status($comment_id, 'spam') ) {
    11301328                add_comment_meta($comment_id, '_wp_trash_meta_status', $comment->comment_approved);
    1131                 do_action('spammed_comment', $comment_id);
     1329                /**
     1330                 * Fires immediately after a comment is marked as Spam.
     1331                 *
     1332                 * @since 2.9.0
     1333                 *
     1334                 * @param int $comment_id The comment ID.
     1335                 */
     1336                do_action( 'spammed_comment', $comment_id );
    11321337                return true;
    11331338        }
    11341339
     
    11491354        if ( ! (int)$comment_id )
    11501355                return false;
    11511356
    1152         do_action('unspam_comment', $comment_id);
     1357        /**
     1358         * Fires immediately before a comment is unmarked as Spam.
     1359         *
     1360         * @since 2.9.0
     1361         *
     1362         * @param int $comment_id The comment ID.
     1363         */
     1364        do_action( 'unspam_comment', $comment_id );
    11531365
    11541366        $status = (string) get_comment_meta($comment_id, '_wp_trash_meta_status', true);
    11551367        if ( empty($status) )
     
    11571369
    11581370        if ( wp_set_comment_status($comment_id, $status) ) {
    11591371                delete_comment_meta($comment_id, '_wp_trash_meta_status');
    1160                 do_action('unspammed_comment', $comment_id);
     1372                /**
     1373                 * Fires immediately after a comment is unmarked as Spam.
     1374                 *
     1375                 * @since 2.9.0
     1376                 *
     1377                 * @param int $comment_id The comment ID.
     1378                 */
     1379                do_action( 'unspammed_comment', $comment_id );
    11611380                return true;
    11621381        }
    11631382
     
    12141433 * @param object $comment Comment data.
    12151434 */
    12161435function wp_transition_comment_status($new_status, $old_status, $comment) {
    1217         // Translate raw statuses to human readable formats for the hooks
    1218         // This is not a complete list of comment status, it's only the ones that need to be renamed
     1436        /*
     1437         * Translate raw statuses to human readable formats for the hooks.
     1438         * This is not a complete list of comment status, it's only the ones
     1439         * that need to be renamed
     1440         */
    12191441        $comment_statuses = array(
    12201442                0         => 'unapproved',
    12211443                'hold'    => 'unapproved', // wp_set_comment_status() uses "hold"
     
    12271449
    12281450        // Call the hooks
    12291451        if ( $new_status != $old_status ) {
    1230                 do_action('transition_comment_status', $new_status, $old_status, $comment);
    1231                 do_action("comment_{$old_status}_to_{$new_status}", $comment);
     1452                /**
     1453                 * Fires when the comment status is in transition.
     1454                 *
     1455                 * @since 2.7.0
     1456                 *
     1457                 * @param int|string $new_status The new comment status.
     1458                 * @param int|string $old_status The old comment status.
     1459                 * @param object     $comment    The comment data.
     1460                 */
     1461                do_action( 'transition_comment_status', $new_status, $old_status, $comment );
     1462                /**
     1463                 * Fires when the comment status is in transition from one specific status to another.
     1464                 *
     1465                 * The dynamic portions of the hook name, $old_status, and $new_status,
     1466                 * refer to the old and new comment statuses, respectively.
     1467                 *
     1468                 * @since 2.7.0
     1469                 *
     1470                 * @param object $comment Comment object.
     1471                 */
     1472                do_action( "comment_{$old_status}_to_{$new_status}", $comment );
    12321473        }
    1233         do_action("comment_{$new_status}_{$comment->comment_type}", $comment->comment_ID, $comment);
     1474        /**
     1475         * Fires when the status of a specific comment type is in transition.
     1476         *
     1477         * The dynamic portions of the hook name, $new_status, and $comment->comment_type,
     1478         * refer to the new comment status, and the type of comment, respectively.
     1479         *
     1480         * Typical comment types include an empty string (standard comment), 'pingback',
     1481         * or 'trackback'.
     1482         *
     1483         * @since 2.7.0
     1484         *
     1485         * @param int $comment_ID The comment ID.
     1486         * @param obj $comment    Comment object.
     1487         */
     1488        do_action( "comment_{$new_status}_{$comment->comment_type}", $comment->comment_ID, $comment );
    12341489}
    12351490
    12361491/**
     
    12601515        if ( isset($_COOKIE['comment_author_url_'.COOKIEHASH]) )
    12611516                $comment_author_url = $_COOKIE['comment_author_url_'.COOKIEHASH];
    12621517
    1263         return apply_filters('wp_get_current_commenter', compact('comment_author', 'comment_author_email', 'comment_author_url'));
     1518        /**
     1519         * Filter the current commenter's name, email, and URL.
     1520         *
     1521         * @since 3.1.0
     1522         *
     1523         * @param string $comment_author       Comment author's name.
     1524         * @param string $comment_author_email Comment author's email.
     1525         * @param string $comment_author_url   Comment author's URL.
     1526         */
     1527        return apply_filters( 'wp_get_current_commenter', compact('comment_author', 'comment_author_email', 'comment_author_url') );
    12641528}
    12651529
    12661530/**
     
    13051569                wp_update_comment_count($comment_post_ID);
    13061570
    13071571        $comment = get_comment($id);
    1308         do_action('wp_insert_comment', $id, $comment);
    13091572
     1573        /**
     1574         * Fires immediately after a comment is inserted into the database.
     1575         *
     1576         * @since 2.8.0
     1577         *
     1578         * @param int $id      The comment ID.
     1579         * @param obj $comment Comment object.
     1580         */
     1581        do_action( 'wp_insert_comment', $id, $comment );
     1582
    13101583        wp_cache_set( 'last_changed', microtime(), 'comment' );
    13111584
    13121585        return $id;
     
    13201593 * filtering the same comment more than once.
    13211594 *
    13221595 * @since 2.0.0
    1323  * @uses apply_filters() Calls 'pre_user_id' hook on comment author's user ID
    1324  * @uses apply_filters() Calls 'pre_comment_user_agent' hook on comment author's user agent
    1325  * @uses apply_filters() Calls 'pre_comment_author_name' hook on comment author's name
    1326  * @uses apply_filters() Calls 'pre_comment_content' hook on the comment's content
    1327  * @uses apply_filters() Calls 'pre_comment_user_ip' hook on comment author's IP
    1328  * @uses apply_filters() Calls 'pre_comment_author_url' hook on comment author's URL
    1329  * @uses apply_filters() Calls 'pre_comment_author_email' hook on comment author's email address
    13301596 *
    13311597 * @param array $commentdata Contains information on the comment.
    13321598 * @return array Parsed comment information.
    13331599 */
    13341600function wp_filter_comment($commentdata) {
    1335         if ( isset($commentdata['user_ID']) )
    1336                 $commentdata['user_id'] = apply_filters('pre_user_id', $commentdata['user_ID']);
    1337         elseif ( isset($commentdata['user_id']) )
    1338                 $commentdata['user_id'] = apply_filters('pre_user_id', $commentdata['user_id']);
    1339         $commentdata['comment_agent']        = apply_filters('pre_comment_user_agent', ( isset( $commentdata['comment_agent'] ) ? $commentdata['comment_agent'] : '' ) );
    1340         $commentdata['comment_author']       = apply_filters('pre_comment_author_name', $commentdata['comment_author']);
    1341         $commentdata['comment_content']      = apply_filters('pre_comment_content', $commentdata['comment_content']);
    1342         $commentdata['comment_author_IP']    = apply_filters('pre_comment_user_ip', $commentdata['comment_author_IP']);
    1343         $commentdata['comment_author_url']   = apply_filters('pre_comment_author_url', $commentdata['comment_author_url']);
    1344         $commentdata['comment_author_email'] = apply_filters('pre_comment_author_email', $commentdata['comment_author_email']);
     1601        if ( isset( $commentdata['user_ID'] ) ) {
     1602                /**
     1603                 * Filter the comment author's user id before it is set.
     1604                 *
     1605                 * The first time this filter is evaluated, 'user_ID' is checked
     1606                 * (for back-compat), followed by the standard 'user_id' value.
     1607                 *
     1608                 * @since 1.5.2
     1609                 *
     1610                 * @param int $user_ID The comment author's user ID.
     1611                 */
     1612                $commentdata['user_id'] = apply_filters( 'pre_user_id', $commentdata['user_ID'] );
     1613        } elseif ( isset( $commentdata['user_id'] ) ) {
     1614                /** This filter is documented in wp-includes/comment.php */
     1615                $commentdata['user_id'] = apply_filters( 'pre_user_id', $commentdata['user_id'] );
     1616        }
     1617
     1618        /**
     1619         * Filter the comment author's browser user agent before it is set.
     1620         *
     1621         * @since 1.5.2
     1622         *
     1623         * @param int $comment_agent The comment author's browser user agent.
     1624         */
     1625        $commentdata['comment_agent'] = apply_filters( 'pre_comment_user_agent', ( isset( $commentdata['comment_agent'] ) ? $commentdata['comment_agent'] : '' ) );
     1626        /** This filter is documented in wp-includes/comment.php */
     1627        $commentdata['comment_author'] = apply_filters( 'pre_comment_author_name', $commentdata['comment_author'] );
     1628        /**
     1629         * Filter the comment content before it is set.
     1630         *
     1631         * @since 1.5.2
     1632         *
     1633         * @param int $comment_content The comment content.
     1634         */
     1635        $commentdata['comment_content'] = apply_filters( 'pre_comment_content', $commentdata['comment_content'] );
     1636        /**
     1637         * Filter the comment author's IP before it is set.
     1638         *
     1639         * @since 1.5.2
     1640         *
     1641         * @param int $comment_author_ip The comment author's IP.
     1642         */
     1643        $commentdata['comment_author_IP'] = apply_filters( 'pre_comment_user_ip', $commentdata['comment_author_IP'] );
     1644        /** This filter is documented in wp-includes/comment.php */
     1645        $commentdata['comment_author_url'] = apply_filters( 'pre_comment_author_url', $commentdata['comment_author_url'] );
     1646        /** This filter is documented in wp-includes/comment.php */
     1647        $commentdata['comment_author_email'] = apply_filters( 'pre_comment_author_email', $commentdata['comment_author_email'] );
    13451648        $commentdata['filtered'] = true;
    13461649        return $commentdata;
    13471650}
    13481651
    13491652/**
    1350  * Whether comment should be blocked because of comment flood.
     1653 * Whether a comment should be blocked because of comment flood.
    13511654 *
    13521655 * @since 2.1.0
    13531656 *
     
    13811684 * @return int The ID of the comment after adding.
    13821685 */
    13831686function wp_new_comment( $commentdata ) {
    1384         $commentdata = apply_filters('preprocess_comment', $commentdata);
     1687        /**
     1688         * Filter a comment's data before it is sanitized and inserted into the database.
     1689         *
     1690         * @since 1.5.2
     1691         *
     1692         * @param array $commentdata Comment data.
     1693         */
     1694        $commentdata = apply_filters( 'preprocess_comment', $commentdata );
    13851695
    13861696        $commentdata['comment_post_ID'] = (int) $commentdata['comment_post_ID'];
    13871697        if ( isset($commentdata['user_ID']) )
     
    14051715
    14061716        $comment_ID = wp_insert_comment($commentdata);
    14071717
    1408         do_action('comment_post', $comment_ID, $commentdata['comment_approved']);
     1718        /**
     1719         * Fires immediately after a comment is inserted into the database.
     1720         *
     1721         * @since 1.2.1
     1722         *
     1723         * @param int $comment_ID       The comment ID.
     1724         * @param int $comment_approved 1 (true) if the comment is approved, 0 (false) if not.
     1725         */
     1726        do_action( 'comment_post', $comment_ID, $commentdata['comment_approved'] );
    14091727
    14101728        if ( 'spam' !== $commentdata['comment_approved'] ) { // If it's spam save it silently for later crunching
    14111729                if ( '0' == $commentdata['comment_approved'] ) {
     
    14751793
    14761794        $comment = get_comment($comment_id);
    14771795
    1478         do_action('wp_set_comment_status', $comment_id, $comment_status);
     1796        /**
     1797         * Fires after a comment status has been updated in the database.
     1798         *
     1799         * The hook also fires immediately before comment status transition hooks are fired.
     1800         *
     1801         * @since 1.5.2
     1802         *
     1803         * @param int         $comment_id     The comment ID.
     1804         * @param string|bool $comment_status The comment status. Possible values include 'hold',
     1805         *                                    'approve', 'spam', 'trash', or false.
     1806         */
     1807        do_action( 'wp_set_comment_status', $comment_id, $comment_status );
    14791808        wp_transition_comment_status($comment_status, $comment_old->comment_approved, $comment);
    14801809
    14811810        wp_update_comment_count($comment->comment_post_ID);
     
    15161845        // Now extract the merged array.
    15171846        extract(wp_unslash($commentarr), EXTR_SKIP);
    15181847
    1519         $comment_content = apply_filters('comment_save_pre', $comment_content);
     1848        /**
     1849         * Filter the comment content before it is updated in the database.
     1850         *
     1851         * @since 1.5.2
     1852         *
     1853         * @param string $comment_content The comment data.
     1854         */
     1855        $comment_content = apply_filters( 'comment_save_pre', $comment_content );
    15201856
    15211857        $comment_date_gmt = get_gmt_from_date($comment_date);
    15221858
     
    15321868
    15331869        clean_comment_cache($comment_ID);
    15341870        wp_update_comment_count($comment_post_ID);
    1535         do_action('edit_comment', $comment_ID);
     1871        /**
     1872         * Fires immediately after a comment is updated in the database.
     1873         *
     1874         * The hook also fires immediately before comment status transition hooks are fired.
     1875         *
     1876         * @since 1.2.1
     1877         *
     1878         * @param int $comment_ID The comment ID.
     1879         */
     1880        do_action( 'edit_comment', $comment_ID );
    15361881        $comment = get_comment($comment_ID);
    15371882        wp_transition_comment_status($comment->comment_approved, $old_status, $comment);
    15381883        return $rval;
     
    16291974
    16301975        clean_post_cache( $post );
    16311976
    1632         do_action('wp_update_comment_count', $post_id, $new, $old);
    1633         do_action('edit_post', $post_id, $post);
     1977        /**
     1978         * Fires immediately after a post's comment count is updated in the database.
     1979         *
     1980         * @since 2.3.0
     1981         *
     1982         * @param int $post_id Post ID.
     1983         * @param int $new     The new comment count.
     1984         * @param int $old     The old comment count.
     1985         */
     1986        do_action( 'wp_update_comment_count', $post_id, $new, $old );
     1987        /** This action is documented in wp-includes/post.php */
     1988        do_action( 'edit_post', $post_id, $post );
    16341989
    16351990        return true;
    16361991}
     
    17602115                return;
    17612116        }
    17622117
    1763         if ( empty($post->post_excerpt) )
    1764                 $excerpt = apply_filters('the_content', $post->post_content, $post->ID);
    1765         else
    1766                 $excerpt = apply_filters('the_excerpt', $post->post_excerpt);
     2118        if ( empty($post->post_excerpt) ) {
     2119                /** This filter is documented in wp-admin/post-template.php */
     2120                $excerpt = apply_filters( 'the_content', $post->post_content, $post->ID );
     2121        } else {
     2122                /** This filter is documented in wp-admin/post-template.php */
     2123                $excerpt = apply_filters( 'the_excerpt', $post->post_excerpt );
     2124        }
     2125
    17672126        $excerpt = str_replace(']]>', ']]&gt;', $excerpt);
    17682127        $excerpt = wp_html_excerpt($excerpt, 252, '&#8230;');
    17692128
    17702129        /** This filter is documented in wp-includes/post-template.php */
    1771         $post_title = apply_filters('the_title', $post->post_title, $post->ID);
     2130        $post_title = apply_filters( 'the_title', $post->post_title, $post->ID );
    17722131        $post_title = strip_tags($post_title);
    17732132
    17742133        if ( $to_ping ) {
     
    18512210        endforeach;
    18522211
    18532212        $post_links = array_unique( $post_links );
     2213        /**
     2214         * Fires just before pinging back links found in a post.
     2215         *
     2216         * @since 2.0.0
     2217         *
     2218         * @param array &$post_links An array of post links to be checked, passed by reference.
     2219         * @param array &$pung       Whether a link has already been pinged, passed by reference.
     2220         * @param int   $post_ID     The post ID.
     2221         */
    18542222        do_action_ref_array( 'pre_ping', array( &$post_links, &$pung, $post_ID ) );
    18552223
    18562224        foreach ( (array) $post_links as $pagelinkedto ) {
     
    18582226
    18592227                if ( $pingback_server_url ) {
    18602228                        @ set_time_limit( 60 );
    1861                          // Now, the RPC call
     2229                        // Now, the RPC call
    18622230                        $pagelinkedfrom = get_permalink($post_ID);
    18632231
    18642232                        // using a timeout of 3 seconds should be enough to cover slow servers
    18652233                        $client = new WP_HTTP_IXR_Client($pingback_server_url);
    18662234                        $client->timeout = 3;
    1867                         $client->useragent = apply_filters( 'pingback_useragent', $client->useragent . ' -- WordPress/' . $wp_version, $client->useragent, $pingback_server_url, $pagelinkedto, $pagelinkedfrom);
     2235                        /**
     2236                         * Filter the user agent sent when pinging-back a URL.
     2237                         *
     2238                         * @since 2.9.0
     2239                         *
     2240                         * @param string $concat_useragent    The user agent concatenated with ' -- WordPress/'
     2241                         *                                    and the WordPress version.
     2242                         * @param string $useragent           The useragent.
     2243                         * @param string $pingback_server_url The server URL being linked to.
     2244                         * @param string $pagelinkedto        URL of page linked to.
     2245                         * @param string $pagelinkedfrom      URL of page linked from.
     2246                         */
     2247                        $client->useragent = apply_filters( 'pingback_useragent', $client->useragent . ' -- WordPress/' . $wp_version, $client->useragent, $pingback_server_url, $pagelinkedto, $pagelinkedfrom );
    18682248                        // when set to true, this outputs debug messages by itself
    18692249                        $client->debug = false;
    18702250
     
    20412421        if ( empty( $posts ) || ! $query->is_singular() || ! get_option( 'close_comments_for_old_posts' ) )
    20422422                return $posts;
    20432423
     2424        /**
     2425         * Filter the list of post types to automatically close comments for.
     2426         *
     2427         * @since 3.2.0
     2428         *
     2429         * @param array $post_types An array of registered post types. Default array with 'post'.
     2430         */
    20442431        $post_types = apply_filters( 'close_comments_for_post_types', array( 'post' ) );
    20452432        if ( ! in_array( $posts[0]->post_type, $post_types ) )
    20462433                return $posts;
     
    20802467
    20812468        $post = get_post($post_id);
    20822469
     2470        /** This filter is documented in wp-includes/comment.php */
    20832471        $post_types = apply_filters( 'close_comments_for_post_types', array( 'post' ) );
    20842472        if ( ! in_array( $post->post_type, $post_types ) )
    20852473                return $open;