Make WordPress Core

Changeset 26491


Ignore:
Timestamp:
12/01/2013 01:11:26 AM (11 years ago)
Author:
DrewAPicture
Message:

Inline documentation for hooks in wp-includes/comment.php.

comment.php, a.k.a. "lots 'o hooks".

Props swissspidy for the initial patch. Props danieldudzic, kpdesign, and DrewAPicture.
Fixes #25522.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/comment.php

    r26388 r26491  
    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
     
    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;
     
    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 ) {
     
    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 );
     
    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 )
     
    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
     
    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);
     
    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;
    652     }
    653 
    654     if ( isset($_COOKIE['comment_author_email_'.COOKIEHASH]) ) {
    655         $comment_author_email = apply_filters('pre_comment_author_email', $_COOKIE['comment_author_email_'.COOKIEHASH]);
     707        $_COOKIE['comment_author_' . COOKIEHASH] = $comment_author;
     708    }
     709
     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);
     
    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;
     
    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') )
     
    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
     
    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) )
     
    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;
     
    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') )
     
    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') );
     
    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;
     
    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.
     
    10361182    if ( ! $wpdb->delete( $wpdb->comments, array( 'comment_ID' => $comment_id ) ) )
    10371183        return false;
    1038     do_action('deleted_comment', $comment_id);
     1184
     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 );
    10391193
    10401194    $post_id = $comment->comment_post_ID;
     
    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;
     
    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    }
     
    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);
     
    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    }
     
    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    }
     
    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);
     
    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    }
     
    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',
     
    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);
    1232     }
    1233     do_action("comment_{$new_status}_{$comment->comment_type}", $comment->comment_ID, $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 );
     1473    }
     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
     
    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
     
    13061570
    13071571    $comment = get_comment($id);
    1308     do_action('wp_insert_comment', $id, $comment);
     1572
     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 );
    13091582
    13101583    wp_cache_set( 'last_changed', microtime(), 'comment' );
     
    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.
     
    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;
     
    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
     
    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'];
     
    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
     
    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
     
    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);
     
    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);
     
    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;
     
    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
     
    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
     
    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
     
    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;
     
    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 ) )
     
    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 ) )
Note: See TracChangeset for help on using the changeset viewer.