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, $ |
44 | 44 | if ( 1 == get_option('comment_moderation') ) |
45 | 45 | return false; // If moderation is set to manual |
46 | 46 | |
| 47 | /** |
| 48 | * Filters the comment text. |
| 49 | * |
| 50 | * @since 1.2.1 |
| 51 | * |
| 52 | * @param string $comment The comment text |
| 53 | */ |
47 | 54 | $comment = apply_filters( 'comment_text', $comment ); |
48 | 55 | |
49 | 56 | // Check # of external links |
50 | 57 | if ( $max_links = get_option( 'comment_max_links' ) ) { |
51 | 58 | $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 | */ |
52 | 68 | $num_links = apply_filters( 'comment_max_links_url', $num_links, $url ); // provide for counting of $url as a link |
53 | 69 | if ( $num_links >= $max_links ) |
54 | 70 | return false; |
… |
… |
function get_comment(&$comment, $output = OBJECT) { |
147 | 163 | } |
148 | 164 | } |
149 | 165 | |
| 166 | /** |
| 167 | * Fires after getting the comment. |
| 168 | * |
| 169 | * @since 2.3.0 |
| 170 | * |
| 171 | * @param mixed $_comment Comment data |
| 172 | */ |
150 | 173 | $_comment = apply_filters('get_comment', $_comment); |
151 | 174 | |
152 | 175 | if ( $output == OBJECT ) { |
… |
… |
class WP_Comment_Query { |
251 | 274 | $this->meta_query = new WP_Meta_Query(); |
252 | 275 | $this->meta_query->parse_query_vars( $this->query_vars ); |
253 | 276 | |
| 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 | */ |
254 | 284 | do_action_ref_array( 'pre_get_comments', array( &$this ) ); |
255 | 285 | extract( $this->query_vars, EXTR_SKIP ); |
256 | 286 | |
… |
… |
class WP_Comment_Query { |
376 | 406 | } |
377 | 407 | |
378 | 408 | $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 | */ |
379 | 418 | $clauses = apply_filters_ref_array( 'comments_clauses', array( compact( $pieces ), &$this ) ); |
380 | 419 | foreach ( $pieces as $piece ) |
381 | 420 | $$piece = isset( $clauses[ $piece ] ) ? $clauses[ $piece ] : ''; |
… |
… |
class WP_Comment_Query { |
389 | 428 | return $wpdb->get_var( $query ); |
390 | 429 | |
391 | 430 | $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 | */ |
392 | 439 | $comments = apply_filters_ref_array( 'the_comments', array( $comments, &$this ) ); |
393 | 440 | |
394 | 441 | wp_cache_add( $cache_key, $comments, 'comment' ); |
… |
… |
function wp_set_comment_cookies($comment, $user) { |
629 | 676 | if ( $user->exists() ) |
630 | 677 | return; |
631 | 678 | |
| 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 | */ |
632 | 686 | $comment_cookie_lifetime = apply_filters('comment_cookie_lifetime', 30000000); |
633 | 687 | setcookie('comment_author_' . COOKIEHASH, $comment->comment_author, time() + $comment_cookie_lifetime, COOKIEPATH, COOKIE_DOMAIN); |
634 | 688 | setcookie('comment_author_email_' . COOKIEHASH, $comment->comment_author_email, time() + $comment_cookie_lifetime, COOKIEPATH, COOKIE_DOMAIN); |
… |
… |
function wp_set_comment_cookies($comment, $user) { |
645 | 699 | */ |
646 | 700 | function sanitize_comment_cookies() { |
647 | 701 | 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 | */ |
648 | 709 | $comment_author = apply_filters('pre_comment_author_name', $_COOKIE['comment_author_'.COOKIEHASH]); |
649 | 710 | $comment_author = wp_unslash($comment_author); |
650 | 711 | $comment_author = esc_attr($comment_author); |
… |
… |
function sanitize_comment_cookies() { |
652 | 713 | } |
653 | 714 | |
654 | 715 | 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 | */ |
655 | 723 | $comment_author_email = apply_filters('pre_comment_author_email', $_COOKIE['comment_author_email_'.COOKIEHASH]); |
656 | 724 | $comment_author_email = wp_unslash($comment_author_email); |
657 | 725 | $comment_author_email = esc_attr($comment_author_email); |
… |
… |
function sanitize_comment_cookies() { |
659 | 727 | } |
660 | 728 | |
661 | 729 | 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 | */ |
662 | 737 | $comment_author_url = apply_filters('pre_comment_author_url', $_COOKIE['comment_author_url_'.COOKIEHASH]); |
663 | 738 | $comment_author_url = wp_unslash($comment_author_url); |
664 | 739 | $_COOKIE['comment_author_url_'.COOKIEHASH] = $comment_author_url; |
… |
… |
function wp_allow_comment($commentdata) { |
688 | 763 | $dupe .= $wpdb->prepare( "OR comment_author_email = %s ", wp_unslash( $comment_author_email ) ); |
689 | 764 | $dupe .= $wpdb->prepare( ") AND comment_content = %s LIMIT 1", wp_unslash( $comment_content ) ); |
690 | 765 | 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 | */ |
691 | 773 | do_action( 'comment_duplicate_trigger', $commentdata ); |
692 | 774 | if ( defined('DOING_AJAX') ) |
693 | 775 | die( __('Duplicate comment detected; it looks as though you’ve already said that!') ); |
… |
… |
function wp_allow_comment($commentdata) { |
695 | 777 | wp_die( __('Duplicate comment detected; it looks as though you’ve already said that!') ); |
696 | 778 | } |
697 | 779 | |
| 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 | */ |
698 | 791 | do_action( 'check_comment_flood', $comment_author_IP, $comment_author_email, $comment_date_gmt ); |
699 | 792 | |
700 | 793 | if ( ! empty( $user_id ) ) { |
… |
… |
function wp_allow_comment($commentdata) { |
705 | 798 | if ( isset( $user ) && ( $user_id == $post_author || $user->has_cap( 'moderate_comments' ) ) ) { |
706 | 799 | // The author and the admins get respect. |
707 | 800 | $approved = 1; |
708 | | } else { |
| 801 | } else { |
709 | 802 | // Everyone else's comments will be checked. |
710 | 803 | if ( check_comment($comment_author, $comment_author_email, $comment_author_url, $comment_content, $comment_author_IP, $comment_agent, $comment_type) ) |
711 | 804 | $approved = 1; |
… |
… |
function wp_allow_comment($commentdata) { |
715 | 808 | $approved = 'spam'; |
716 | 809 | } |
717 | 810 | |
| 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 | */ |
718 | 819 | $approved = apply_filters( 'pre_comment_approved', $approved, $commentdata ); |
719 | 820 | return $approved; |
720 | 821 | } |
… |
… |
function check_comment_flood_db( $ip, $email, $date ) { |
744 | 845 | 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 ) ) ) { |
745 | 846 | $time_lastcomment = mysql2date('U', $lasttime, false); |
746 | 847 | $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 | */ |
747 | 857 | $flood_die = apply_filters('comment_flood_filter', false, $time_lastcomment, $time_newcomment); |
748 | 858 | 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 | */ |
749 | 867 | do_action('comment_flood_trigger', $time_lastcomment, $time_newcomment); |
750 | 868 | |
751 | 869 | if ( defined('DOING_AJAX') ) |
… |
… |
function get_page_of_comment( $comment_ID, $args = array() ) { |
902 | 1020 | * @return bool True if comment contains blacklisted content, false if comment does not |
903 | 1021 | */ |
904 | 1022 | function 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 | */ |
905 | 1035 | do_action('wp_blacklist_check', $author, $email, $url, $comment, $user_ip, $user_agent); |
906 | 1036 | |
907 | 1037 | $mod_keys = trim( get_option('blacklist_keys') ); |
… |
… |
function wp_blacklist_check($author, $email, $url, $comment, $user_ip, $user_age |
921 | 1051 | |
922 | 1052 | $pattern = "#$word#i"; |
923 | 1053 | if ( |
924 | | preg_match($pattern, $author) |
| 1054 | preg_match($pattern, $author) |
925 | 1055 | || preg_match($pattern, $email) |
926 | 1056 | || preg_match($pattern, $url) |
927 | 1057 | || preg_match($pattern, $comment) |
928 | 1058 | || preg_match($pattern, $user_ip) |
929 | 1059 | || preg_match($pattern, $user_agent) |
930 | | ) |
| 1060 | ) |
931 | 1061 | return true; |
932 | 1062 | } |
933 | 1063 | return false; |
… |
… |
function wp_count_comments( $post_id = 0 ) { |
954 | 1084 | |
955 | 1085 | $post_id = (int) $post_id; |
956 | 1086 | |
| 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 | */ |
957 | 1095 | $stats = apply_filters('wp_count_comments', array(), $post_id); |
958 | 1096 | if ( !empty($stats) ) |
959 | 1097 | return $stats; |
… |
… |
function wp_delete_comment($comment_id, $force_delete = false) { |
1019 | 1157 | if ( !$force_delete && EMPTY_TRASH_DAYS && !in_array( wp_get_comment_status($comment_id), array( 'trash', 'spam' ) ) ) |
1020 | 1158 | return wp_trash_comment($comment_id); |
1021 | 1159 | |
| 1160 | /** |
| 1161 | * Fires before deleting a comment. |
| 1162 | * |
| 1163 | * @since 2.1.0 |
| 1164 | * |
| 1165 | * @param int $comment_id Comment ID |
| 1166 | */ |
1022 | 1167 | do_action('delete_comment', $comment_id); |
1023 | 1168 | |
1024 | 1169 | // Move children up a level. |
… |
… |
function wp_delete_comment($comment_id, $force_delete = false) { |
1035 | 1180 | |
1036 | 1181 | if ( ! $wpdb->delete( $wpdb->comments, array( 'comment_ID' => $comment_id ) ) ) |
1037 | 1182 | 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 | */ |
1038 | 1191 | do_action('deleted_comment', $comment_id); |
1039 | 1192 | |
1040 | 1193 | $post_id = $comment->comment_post_ID; |
… |
… |
function wp_delete_comment($comment_id, $force_delete = false) { |
1043 | 1196 | |
1044 | 1197 | clean_comment_cache($comment_id); |
1045 | 1198 | |
| 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 | */ |
1046 | 1207 | do_action('wp_set_comment_status', $comment_id, 'delete'); |
1047 | 1208 | wp_transition_comment_status('delete', $comment->comment_approved, $comment); |
1048 | 1209 | return true; |
… |
… |
function wp_trash_comment($comment_id) { |
1068 | 1229 | if ( !$comment = get_comment($comment_id) ) |
1069 | 1230 | return false; |
1070 | 1231 | |
| 1232 | /** |
| 1233 | * Fires before a comment is trashed. |
| 1234 | * |
| 1235 | * @since 2.9.0 |
| 1236 | * |
| 1237 | * @param int $comment_id Comment ID |
| 1238 | */ |
1071 | 1239 | do_action('trash_comment', $comment_id); |
1072 | 1240 | |
1073 | 1241 | if ( wp_set_comment_status($comment_id, 'trash') ) { |
1074 | 1242 | add_comment_meta($comment_id, '_wp_trash_meta_status', $comment->comment_approved); |
1075 | 1243 | 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 | */ |
1076 | 1252 | do_action('trashed_comment', $comment_id); |
1077 | 1253 | return true; |
1078 | 1254 | } |
… |
… |
function wp_untrash_comment($comment_id) { |
1094 | 1270 | if ( ! (int)$comment_id ) |
1095 | 1271 | return false; |
1096 | 1272 | |
| 1273 | /** |
| 1274 | * Fires before a comment is untrashed. |
| 1275 | * |
| 1276 | * @since 2.9.0 |
| 1277 | * |
| 1278 | * @param int $comment_id Comment ID |
| 1279 | */ |
1097 | 1280 | do_action('untrash_comment', $comment_id); |
1098 | 1281 | |
1099 | 1282 | $status = (string) get_comment_meta($comment_id, '_wp_trash_meta_status', true); |
… |
… |
function wp_untrash_comment($comment_id) { |
1103 | 1286 | if ( wp_set_comment_status($comment_id, $status) ) { |
1104 | 1287 | delete_comment_meta($comment_id, '_wp_trash_meta_time'); |
1105 | 1288 | 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 | */ |
1106 | 1296 | do_action('untrashed_comment', $comment_id); |
1107 | 1297 | return true; |
1108 | 1298 | } |
… |
… |
function wp_spam_comment($comment_id) { |
1124 | 1314 | if ( !$comment = get_comment($comment_id) ) |
1125 | 1315 | return false; |
1126 | 1316 | |
| 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 | */ |
1127 | 1324 | do_action('spam_comment', $comment_id); |
1128 | 1325 | |
1129 | 1326 | if ( wp_set_comment_status($comment_id, 'spam') ) { |
1130 | 1327 | 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 | */ |
1131 | 1335 | do_action('spammed_comment', $comment_id); |
1132 | 1336 | return true; |
1133 | 1337 | } |
… |
… |
function wp_unspam_comment($comment_id) { |
1149 | 1353 | if ( ! (int)$comment_id ) |
1150 | 1354 | return false; |
1151 | 1355 | |
| 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 | */ |
1152 | 1363 | do_action('unspam_comment', $comment_id); |
1153 | 1364 | |
1154 | 1365 | $status = (string) get_comment_meta($comment_id, '_wp_trash_meta_status', true); |
… |
… |
function wp_unspam_comment($comment_id) { |
1157 | 1368 | |
1158 | 1369 | if ( wp_set_comment_status($comment_id, $status) ) { |
1159 | 1370 | 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 | */ |
1160 | 1379 | do_action('unspammed_comment', $comment_id); |
1161 | 1380 | return true; |
1162 | 1381 | } |
… |
… |
function wp_insert_comment($commentdata) { |
1305 | 1524 | wp_update_comment_count($comment_post_ID); |
1306 | 1525 | |
1307 | 1526 | $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 | */ |
1308 | 1536 | do_action('wp_insert_comment', $id, $comment); |
1309 | 1537 | |
1310 | 1538 | wp_cache_set( 'last_changed', microtime(), 'comment' ); |
… |
… |
function pingback($content, $post_ID) { |
1862 | 2090 | |
1863 | 2091 | if ( $pingback_server_url ) { |
1864 | 2092 | @ set_time_limit( 60 ); |
1865 | | // Now, the RPC call |
| 2093 | // Now, the RPC call |
1866 | 2094 | $pagelinkedfrom = get_permalink($post_ID); |
1867 | 2095 | |
1868 | 2096 | // using a timeout of 3 seconds should be enough to cover slow servers |
… |
… |
function _close_comments_for_old_posts( $posts, $query ) { |
2045 | 2273 | if ( empty( $posts ) || ! $query->is_singular() || ! get_option( 'close_comments_for_old_posts' ) ) |
2046 | 2274 | return $posts; |
2047 | 2275 | |
| 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 | */ |
2048 | 2283 | $post_types = apply_filters( 'close_comments_for_post_types', array( 'post' ) ); |
2049 | 2284 | if ( ! in_array( $posts[0]->post_type, $post_types ) ) |
2050 | 2285 | return $posts; |
… |
… |
function _close_comments_for_old_post( $open, $post_id ) { |
2084 | 2319 | |
2085 | 2320 | $post = get_post($post_id); |
2086 | 2321 | |
| 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 | */ |
2087 | 2329 | $post_types = apply_filters( 'close_comments_for_post_types', array( 'post' ) ); |
2088 | 2330 | if ( ! in_array( $post->post_type, $post_types ) ) |
2089 | 2331 | return $open; |