WordPress.org

Make WordPress Core

Ticket #25522: 25522.diff

File 25522.diff, 16.0 KB (added by swissspidy, 8 years ago)

  • src/wp-includes/comment.php 

    From 5b3e505768fa35b16653f2ca606d124ea4aafed6 Mon Sep 17 00:00:00 2001
From: swissspidy <hello@pascalbirchler.ch>
Date: Mon, 7 Oct 2013 18:14:58 +0200
Subject: [PATCH] Hooks Docs: wp-includes/comment.php

---
 src/wp-includes/comment.php | 250 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 246 insertions(+), 4 deletions(-)

diff --git a/src/wp-includes/comment.php b/src/wp-includes/comment.php
index 9692768..1a6d9f4 100644
    a b function check_comment($author, $email, $url, $comment, $user_ip, $user_agent, $ 
    4444        if ( 1 == get_option('comment_moderation') )
    4545                return false; // If moderation is set to manual
    4646
     47        /**
     48         * Filters the comment text.
     49         *
     50         * @since 1.2.1
     51         *
     52         * @param string $comment The comment text
     53         */
    4754        $comment = apply_filters( 'comment_text', $comment );
    4855
    4956        // Check # of external links
    5057        if ( $max_links = get_option( 'comment_max_links' ) ) {
    5158                $num_links = preg_match_all( '/<a [^>]*href/i', $comment, $out );
     59
     60                /**
     61                 * Filters the maximum amount of links allowed in a comment
     62                 *
     63                 * @since 3.0.0
     64                 *
     65                 * @param int    $num_links The number of links allowed
     66                 * @param string $url       Comment Author's URL
     67                 */
    5268                $num_links = apply_filters( 'comment_max_links_url', $num_links, $url ); // provide for counting of $url as a link
    5369                if ( $num_links >= $max_links )
    5470                        return false;
    … … function get_comment(&$comment, $output = OBJECT) { 
    147163                }
    148164        }
    149165
     166        /**
     167         * Fires after getting the comment.
     168         *
     169         * @since 2.3.0
     170         *
     171         * @param mixed $_comment Comment data
     172         */
    150173        $_comment = apply_filters('get_comment', $_comment);
    151174
    152175        if ( $output == OBJECT ) {
    … … class WP_Comment_Query { 
    251274                $this->meta_query = new WP_Meta_Query();
    252275                $this->meta_query->parse_query_vars( $this->query_vars );
    253276
     277                /**
     278                 * Fires before getting the comments
     279                 *
     280                 * @since 3.1.0
     281                 *
     282                 * @param array Array containing the current instance of WP_Comment_Query
     283                 */
    254284                do_action_ref_array( 'pre_get_comments', array( &$this ) );
    255285                extract( $this->query_vars, EXTR_SKIP );
    256286
    … … class WP_Comment_Query { 
    376406                }
    377407
    378408                $pieces = array( 'fields', 'join', 'where', 'orderby', 'order', 'limits', 'groupby' );
     409
     410                /**
     411                 * Filters the comments clauses
     412                 *
     413                 * @since 3.1.0
     414                 *
     415                 * @param array An array containing all the pieces
     416                 * @param
     417                 */
    379418                $clauses = apply_filters_ref_array( 'comments_clauses', array( compact( $pieces ), &$this ) );
    380419                foreach ( $pieces as $piece )
    381420                        $$piece = isset( $clauses[ $piece ] ) ? $clauses[ $piece ] : '';
    … … class WP_Comment_Query { 
    389428                        return $wpdb->get_var( $query );
    390429
    391430                $comments = $wpdb->get_results( $query );
     431
     432                /**
     433                 * Filters the resulting comments
     434                 *
     435                 * @since 3.1.0
     436                 *
     437                 * @param array An array containing the comments and the current instance of WP_Comment_Query
     438                 */
    392439                $comments = apply_filters_ref_array( 'the_comments', array( $comments, &$this ) );
    393440
    394441                wp_cache_add( $cache_key, $comments, 'comment' );
    … … function wp_set_comment_cookies($comment, $user) { 
    629676        if ( $user->exists() )
    630677                return;
    631678
     679        /**
     680         * Filters the lifetime of the comment cookie
     681         *
     682         * @since 2.8.0
     683         *
     684         * @param int Comment cookie lifetime. Default is 30000000 seconds (ca. 347 days)
     685         */
    632686        $comment_cookie_lifetime = apply_filters('comment_cookie_lifetime', 30000000);
    633687        setcookie('comment_author_' . COOKIEHASH, $comment->comment_author, time() + $comment_cookie_lifetime, COOKIEPATH, COOKIE_DOMAIN);
    634688        setcookie('comment_author_email_' . COOKIEHASH, $comment->comment_author_email, time() + $comment_cookie_lifetime, COOKIEPATH, COOKIE_DOMAIN);
    … … function wp_set_comment_cookies($comment, $user) { 
    645699 */
    646700function sanitize_comment_cookies() {
    647701        if ( isset($_COOKIE['comment_author_'.COOKIEHASH]) ) {
     702                /**
     703                 * Filters the comment author's name cookie
     704                 *
     705                 * @since 2.1.0
     706                 *
     707                 * @param string The comment author name
     708                 */
    648709                $comment_author = apply_filters('pre_comment_author_name', $_COOKIE['comment_author_'.COOKIEHASH]);
    649710                $comment_author = wp_unslash($comment_author);
    650711                $comment_author = esc_attr($comment_author);
    … … function sanitize_comment_cookies() { 
    652713        }
    653714
    654715        if ( isset($_COOKIE['comment_author_email_'.COOKIEHASH]) ) {
     716                /**
     717                 * Filters the comment author's email cookie
     718                 *
     719                 * @since 2.8.0
     720                 *
     721                 * @param string The comment author email
     722                 */
    655723                $comment_author_email = apply_filters('pre_comment_author_email', $_COOKIE['comment_author_email_'.COOKIEHASH]);
    656724                $comment_author_email = wp_unslash($comment_author_email);
    657725                $comment_author_email = esc_attr($comment_author_email);
    … … function sanitize_comment_cookies() { 
    659727        }
    660728
    661729        if ( isset($_COOKIE['comment_author_url_'.COOKIEHASH]) ) {
     730                /**
     731                 * Filters the comment author's URL cookie
     732                 *
     733                 * @since 2.1.0
     734                 *
     735                 * @param string The comment author URL
     736                 */
    662737                $comment_author_url = apply_filters('pre_comment_author_url', $_COOKIE['comment_author_url_'.COOKIEHASH]);
    663738                $comment_author_url = wp_unslash($comment_author_url);
    664739                $_COOKIE['comment_author_url_'.COOKIEHASH] = $comment_author_url;
    … … function wp_allow_comment($commentdata) { 
    688763                $dupe .= $wpdb->prepare( "OR comment_author_email = %s ", wp_unslash( $comment_author_email ) );
    689764        $dupe .= $wpdb->prepare( ") AND comment_content = %s LIMIT 1", wp_unslash( $comment_content ) );
    690765        if ( $wpdb->get_var($dupe) ) {
     766                /**
     767                 * Fires when a duplicate comment is detected.
     768                 *
     769                 * @since 3.0.0
     770                 *
     771                 * @param array $commentdata Contains information on the comment
     772                 */
    691773                do_action( 'comment_duplicate_trigger', $commentdata );
    692774                if ( defined('DOING_AJAX') )
    693775                        die( __('Duplicate comment detected; it looks as though you&#8217;ve already said that!') );
    … … function wp_allow_comment($commentdata) { 
    695777                wp_die( __('Duplicate comment detected; it looks as though you&#8217;ve already said that!') );
    696778        }
    697779
     780        /**
     781         * Fires before a comment gets approved.
     782         *
     783         * Allows for checking of comment flooding.
     784         *
     785         * @since 2.3.0
     786         *
     787         * @param string $comment_author_IP    The comment author's IP address
     788         * @param string $comment_author_email The comment author's email
     789         * @param string $comment_date_gmt     The date the comment was posted in GMT
     790         */
    698791        do_action( 'check_comment_flood', $comment_author_IP, $comment_author_email, $comment_date_gmt );
    699792
    700793        if ( ! empty( $user_id ) ) {
    … … function wp_allow_comment($commentdata) { 
    705798        if ( isset( $user ) && ( $user_id == $post_author || $user->has_cap( 'moderate_comments' ) ) ) {
    706799                // The author and the admins get respect.
    707800                $approved = 1;
    708          } else {
     801        } else {
    709802                // Everyone else's comments will be checked.
    710803                if ( check_comment($comment_author, $comment_author_email, $comment_author_url, $comment_content, $comment_author_IP, $comment_agent, $comment_type) )
    711804                        $approved = 1;
    … … function wp_allow_comment($commentdata) { 
    715808                        $approved = 'spam';
    716809        }
    717810
     811        /**
     812         * Filters the comment's approval status
     813         *
     814         * @since 2.1.0
     815         *
     816         * @param mixed $approved    The approval status. Default is either 1, 0 or 'spam'
     817         * @param array $commentdata Contains information on the comment
     818         */
    718819        $approved = apply_filters( 'pre_comment_approved', $approved, $commentdata );
    719820        return $approved;
    720821}
    … … function check_comment_flood_db( $ip, $email, $date ) { 
    744845        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 ) ) ) {
    745846                $time_lastcomment = mysql2date('U', $lasttime, false);
    746847                $time_newcomment  = mysql2date('U', $date, false);
     848                /**
     849                 * Filters the comment flood variable.
     850                 *
     851                 * @since 2.1.0
     852                 *
     853                 * @param bool                     True if comment flooding is happening, false if not. Default is false.
     854                 * @param string $time_lastcomment Time when the last comment was posted
     855                 * @param string $time_newcomment  Time when the new comment was posted
     856                 */
    747857                $flood_die = apply_filters('comment_flood_filter', false, $time_lastcomment, $time_newcomment);
    748858                if ( $flood_die ) {
     859                        /**
     860                         * Fires before comment flooding message is triggered
     861                         *
     862                         * @since 2.1.0
     863                         *
     864                         * @param string $time_lastcomment Time when the last comment was posted
     865                         * @param string $time_newcomment  Time when the new comment was posted
     866                         */
    749867                        do_action('comment_flood_trigger', $time_lastcomment, $time_newcomment);
    750868
    751869                        if ( defined('DOING_AJAX') )
    … … function get_page_of_comment( $comment_ID, $args = array() ) { 
    9021020 * @return bool True if comment contains blacklisted content, false if comment does not
    9031021 */
    9041022function wp_blacklist_check($author, $email, $url, $comment, $user_ip, $user_agent) {
     1023        /**
     1024         * Fires before the comment is tested for blacklisted characters or words.
     1025         *
     1026         * @since 1.5.0
     1027         *
     1028         * @param string $author     The author of the comment
     1029         * @param string $email      The email of the comment
     1030         * @param string $url        The url used in the comment
     1031         * @param string $comment    The comment content
     1032         * @param string $user_ip    The comment author IP address
     1033         * @param string $user_agent The author's browser user agent
     1034         */
    9051035        do_action('wp_blacklist_check', $author, $email, $url, $comment, $user_ip, $user_agent);
    9061036
    9071037        $mod_keys = trim( get_option('blacklist_keys') );
    … … function wp_blacklist_check($author, $email, $url, $comment, $user_ip, $user_age 
    9211051
    9221052                $pattern = "#$word#i";
    9231053                if (
    924                            preg_match($pattern, $author)
     1054                                preg_match($pattern, $author)
    9251055                        || preg_match($pattern, $email)
    9261056                        || preg_match($pattern, $url)
    9271057                        || preg_match($pattern, $comment)
    9281058                        || preg_match($pattern, $user_ip)
    9291059                        || preg_match($pattern, $user_agent)
    930                  )
     1060                )
    9311061                        return true;
    9321062        }
    9331063        return false;
    … … function wp_count_comments( $post_id = 0 ) { 
    9541084
    9551085        $post_id = (int) $post_id;
    9561086
     1087        /**
     1088         * Filters the comments count for the given post.
     1089         *
     1090         * @since
     1091         *
     1092         * @param array        An empty array
     1093         * @param int $post_id Post ID
     1094         */
    9571095        $stats = apply_filters('wp_count_comments', array(), $post_id);
    9581096        if ( !empty($stats) )
    9591097                return $stats;
    … … function wp_delete_comment($comment_id, $force_delete = false) { 
    10191157        if ( !$force_delete && EMPTY_TRASH_DAYS && !in_array( wp_get_comment_status($comment_id), array( 'trash', 'spam' ) ) )
    10201158                return wp_trash_comment($comment_id);
    10211159
     1160        /**
     1161         * Fires before deleting a comment.
     1162         *
     1163         * @since 2.1.0
     1164         *
     1165         * @param int $comment_id Comment ID
     1166         */
    10221167        do_action('delete_comment', $comment_id);
    10231168
    10241169        // Move children up a level.
    … … function wp_delete_comment($comment_id, $force_delete = false) { 
    10351180
    10361181        if ( ! $wpdb->delete( $wpdb->comments, array( 'comment_ID' => $comment_id ) ) )
    10371182                return false;
     1183
     1184        /**
     1185         * Fires after comment metadata has been deleted.
     1186         *
     1187         * @since 2.9.0
     1188         *
     1189         * @param int $comment_id Comment ID
     1190         */
    10381191        do_action('deleted_comment', $comment_id);
    10391192
    10401193        $post_id = $comment->comment_post_ID;
    … … function wp_delete_comment($comment_id, $force_delete = false) { 
    10431196
    10441197        clean_comment_cache($comment_id);
    10451198
     1199        /**
     1200         * Fires before transitioning the comment's status to 'delete'.
     1201         *
     1202         * @since 2.1.0
     1203         *
     1204         * @param int $comment_id Comment ID
     1205         * @param string          The new status 'delete'
     1206         */
    10461207        do_action('wp_set_comment_status', $comment_id, 'delete');
    10471208        wp_transition_comment_status('delete', $comment->comment_approved, $comment);
    10481209        return true;
    … … function wp_trash_comment($comment_id) { 
    10681229        if ( !$comment = get_comment($comment_id) )
    10691230                return false;
    10701231
     1232        /**
     1233         * Fires before a comment is trashed.
     1234         *
     1235         * @since 2.9.0
     1236         *
     1237         * @param int $comment_id Comment ID
     1238         */
    10711239        do_action('trash_comment', $comment_id);
    10721240
    10731241        if ( wp_set_comment_status($comment_id, 'trash') ) {
    10741242                add_comment_meta($comment_id, '_wp_trash_meta_status', $comment->comment_approved);
    10751243                add_comment_meta($comment_id, '_wp_trash_meta_time', time() );
     1244
     1245                /**
     1246                 * Fires after a comment is trashed.
     1247                 *
     1248                 * @since 2.9.0
     1249                 *
     1250                 * @param int $comment_id Comment ID
     1251                 */
    10761252                do_action('trashed_comment', $comment_id);
    10771253                return true;
    10781254        }
    … … function wp_untrash_comment($comment_id) { 
    10941270        if ( ! (int)$comment_id )
    10951271                return false;
    10961272
     1273        /**
     1274         * Fires before a comment is untrashed.
     1275         *
     1276         * @since 2.9.0
     1277         *
     1278         * @param int $comment_id Comment ID
     1279         */
    10971280        do_action('untrash_comment', $comment_id);
    10981281
    10991282        $status = (string) get_comment_meta($comment_id, '_wp_trash_meta_status', true);
    … … function wp_untrash_comment($comment_id) { 
    11031286        if ( wp_set_comment_status($comment_id, $status) ) {
    11041287                delete_comment_meta($comment_id, '_wp_trash_meta_time');
    11051288                delete_comment_meta($comment_id, '_wp_trash_meta_status');
     1289                /**
     1290                 * Fires after a comment is untrashed.
     1291                 *
     1292                 * @since 2.9.0
     1293                 *
     1294                 * @param int $comment_id Comment ID
     1295                 */
    11061296                do_action('untrashed_comment', $comment_id);
    11071297                return true;
    11081298        }
    … … function wp_spam_comment($comment_id) { 
    11241314        if ( !$comment = get_comment($comment_id) )
    11251315                return false;
    11261316
     1317        /**
     1318         * Fires before a comment is marked as spam.
     1319         *
     1320         * @since 2.9.0
     1321         *
     1322         * @param int $comment_id Comment ID
     1323         */
    11271324        do_action('spam_comment', $comment_id);
    11281325
    11291326        if ( wp_set_comment_status($comment_id, 'spam') ) {
    11301327                add_comment_meta($comment_id, '_wp_trash_meta_status', $comment->comment_approved);
     1328                /**
     1329                 * Fires after a comment is marked as spam.
     1330                 *
     1331                 * @since 2.9.0
     1332                 *
     1333                 * @param int $comment_id Comment ID
     1334                 */
    11311335                do_action('spammed_comment', $comment_id);
    11321336                return true;
    11331337        }
    … … function wp_unspam_comment($comment_id) { 
    11491353        if ( ! (int)$comment_id )
    11501354                return false;
    11511355
     1356        /**
     1357         * Fires before a comment is removed from the Spam.
     1358         *
     1359         * @since 2.9.0
     1360         *
     1361         * @param int $comment_id Comment ID
     1362         */
    11521363        do_action('unspam_comment', $comment_id);
    11531364
    11541365        $status = (string) get_comment_meta($comment_id, '_wp_trash_meta_status', true);
    … … function wp_unspam_comment($comment_id) { 
    11571368
    11581369        if ( wp_set_comment_status($comment_id, $status) ) {
    11591370                delete_comment_meta($comment_id, '_wp_trash_meta_status');
     1371
     1372                /**
     1373                 * Fires after a comment is removed from the Spam.
     1374                 *
     1375                 * @since 2.9.0
     1376                 *
     1377                 * @param int $comment_id Comment ID
     1378                 */
    11601379                do_action('unspammed_comment', $comment_id);
    11611380                return true;
    11621381        }
    … … function wp_insert_comment($commentdata) { 
    13051524                wp_update_comment_count($comment_post_ID);
    13061525
    13071526        $comment = get_comment($id);
     1527
     1528        /**
     1529         * Fires after the comment is inserted.
     1530         *
     1531         * @since
     1532         *
     1533         * @param int $id Comment ID
     1534         * @param mixed   Comment data
     1535         */
    13081536        do_action('wp_insert_comment', $id, $comment);
    13091537
    13101538        wp_cache_set( 'last_changed', microtime(), 'comment' );
    … … function pingback($content, $post_ID) { 
    18622090
    18632091                if ( $pingback_server_url ) {
    18642092                        @ set_time_limit( 60 );
    1865                          // Now, the RPC call
     2093                        // Now, the RPC call
    18662094                        $pagelinkedfrom = get_permalink($post_ID);
    18672095
    18682096                        // using a timeout of 3 seconds should be enough to cover slow servers
    … … function _close_comments_for_old_posts( $posts, $query ) { 
    20452273        if ( empty( $posts ) || ! $query->is_singular() || ! get_option( 'close_comments_for_old_posts' ) )
    20462274                return $posts;
    20472275
     2276        /**
     2277         * Filters the post types on which old comments should be closed automatically.
     2278         *
     2279         * @since 3.2.0
     2280         *
     2281         * @param array An array of registered post types
     2282         */
    20482283        $post_types = apply_filters( 'close_comments_for_post_types', array( 'post' ) );
    20492284        if ( ! in_array( $posts[0]->post_type, $post_types ) )
    20502285                return $posts;
    … … function _close_comments_for_old_post( $open, $post_id ) { 
    20842319
    20852320        $post = get_post($post_id);
    20862321
     2322        /**
     2323         * Filters the post types on which old comments should be closed automatically.
     2324         *
     2325         * @since 3.2.0
     2326         *
     2327         * @param array An array of registered post types
     2328         */
    20872329        $post_types = apply_filters( 'close_comments_for_post_types', array( 'post' ) );
    20882330        if ( ! in_array( $post->post_type, $post_types ) )
    20892331                return $open;