enmi-conf.org: comparison wp/wp-includes/comment.php

equal deleted inserted replaced

-:be944660c56a
+:3d72ae0968f4
 * @package WordPress
 * @subpackage Comment
 */
 /**
-* Check whether a comment passes internal checks to be allowed to add.
+* Checks whether a comment passes internal checks to be allowed to add.
 *
 * If manual comment moderation is set in the administration, then all checks,
 * regardless of their type and substance, will fail and the function will
 * return false.
 *
 	}
 	return true;
 }
 /**
-* Retrieve the approved comments for post $post_id.
+* Retrieves the approved comments for post $post_id.
 *
 * @since 2.0.0
 * @since 4.1.0 Refactored to leverage WP_Comment_Query over a direct query.
 *
 * @param int   $post_id The ID of the post.
 * @param array $args    Optional. See WP_Comment_Query::__construct() for information on accepted arguments.
-* @return int|array The approved comments, or number of comments if `$count`
+* @return WP_Comment[]|int[]|int The approved comments, or number of comments if `$count`
-*                   argument is true.
+*                                argument is true.
 */
 function get_approved_comments( $post_id, $args = array() ) {
 	if ( ! $post_id ) {
 		return array();
 	}
 	}
 	return $_comment;
 }
 /**
-* Retrieve a list of comments.
+* Retrieves a list of comments.
 *
 * The comment list can be for the blog as a whole or for an individual post.
 *
 * @since 2.7.0
 *
 * @param string|array $args Optional. Array or string of arguments. See WP_Comment_Query::__construct()
 *                           for information on accepted arguments. Default empty.
-* @return int|array List of comments or number of found comments if `$count` argument is true.
+* @return WP_Comment[]|int[]|int List of comments or number of found comments if `$count` argument is true.
 */
 function get_comments( $args = '' ) {
 	$query = new WP_Comment_Query;
 	return $query->query( $args );
 }
 /**
-* Retrieve all of the WordPress supported comment statuses.
+* Retrieves all of the WordPress supported comment statuses.
 *
 * Comments have a limited set of valid status values, this provides the comment
 * status values and descriptions.
 *
 * @since 2.7.0
 	 */
 	return apply_filters( 'get_default_comment_status', $status, $post_type, $comment_type );
 }
 /**
-* The date the last comment was modified.
+* Retrieves the date the last comment was modified.
 *
 * @since 1.5.0
 * @since 4.7.0 Replaced caching the modified date in a local static variable
 *              with the Object Cache API.
 *
 }
 /**
 * Retrieves the total comment counts for the whole site or a single post.
 *
-* Unlike wp_count_comments(), this function always returns the live comment counts without caching.
-*
 * @since 2.0.0
-*
-* @global wpdb $wpdb WordPress database abstraction object.
 *
 * @param int $post_id Optional. Restrict the comment counts to the given post. Default 0, which indicates that
 *                     comment counts for the whole site will be retrieved.
-* @return array() {
+* @return int[] {
 *     The number of comments keyed by their status.
 *
 *     @type int $approved            The number of approved comments.
 *     @type int $awaiting_moderation The number of comments awaiting moderation (a.k.a. pending).
 *     @type int $spam                The number of spam comments.
 *     @type int $total_comments      The total number of non-trashed comments, including spam.
 *     @type int $all                 The total number of pending or approved comments.
 * }
 */
 function get_comment_count( $post_id = 0 ) {
-	global $wpdb;
 	$post_id = (int) $post_id;
-	$where = '';
-	if ( $post_id > 0 ) {
-		$where = $wpdb->prepare( 'WHERE comment_post_ID = %d', $post_id );
-	}
-	$totals = (array) $wpdb->get_results(
-		"
-		SELECT comment_approved, COUNT( * ) AS total
-		FROM {$wpdb->comments}
-		{$where}
-		GROUP BY comment_approved
-	",
-		ARRAY_A
-	);
 	$comment_count = array(
 		'approved'            => 0,
 		'awaiting_moderation' => 0,
 		'spam'                => 0,
 		'post-trashed'        => 0,
 		'total_comments'      => 0,
 		'all'                 => 0,
 	);
-	foreach ( $totals as $row ) {
+	$args = array(
-		switch ( $row['comment_approved'] ) {
+		'count'                     => true,
-			case 'trash':
+		'update_comment_meta_cache' => false,
-				$comment_count['trash'] = $row['total'];
+	);
-				break;
+	if ( $post_id > 0 ) {
-			case 'post-trashed':
+		$args['post_id'] = $post_id;
-				$comment_count['post-trashed'] = $row['total'];
+	}
-				break;
+	$mapping       = array(
-			case 'spam':
+		'approved'            => 'approve',
-				$comment_count['spam']            = $row['total'];
+		'awaiting_moderation' => 'hold',
-				$comment_count['total_comments'] += $row['total'];
+		'spam'                => 'spam',
-				break;
+		'trash'               => 'trash',
-			case '1':
+		'post-trashed'        => 'post-trashed',
-				$comment_count['approved']        = $row['total'];
+	);
-				$comment_count['total_comments'] += $row['total'];
+	$comment_count = array();
-				$comment_count['all']            += $row['total'];
+	foreach ( $mapping as $key => $value ) {
-				break;
+		$comment_count[ $key ] = get_comments( array_merge( $args, array( 'status' => $value ) ) );
-			case '0':
+	}
-				$comment_count['awaiting_moderation'] = $row['total'];
-				$comment_count['total_comments']     += $row['total'];
+	$comment_count['all']            = $comment_count['approved'] + $comment_count['awaiting_moderation'];
-				$comment_count['all']                += $row['total'];
+	$comment_count['total_comments'] = $comment_count['all'] + $comment_count['spam'];
-				break;
-			default:
-				break;
-		}
-	}
 	return array_map( 'intval', $comment_count );
 }
 //
 // Comment meta functions.
 //
 /**
-* Add meta data field to a comment.
+* Adds meta data field to a comment.
 *
 * @since 2.9.0
 *
 * @link https://developer.wordpress.org/reference/functions/add_comment_meta/
 *
 function add_comment_meta( $comment_id, $meta_key, $meta_value, $unique = false ) {
 	return add_metadata( 'comment', $comment_id, $meta_key, $meta_value, $unique );
 }
 /**
-* Remove metadata matching criteria from a comment.
+* Removes metadata matching criteria from a comment.
 *
 * You can match based on the key, or key and value. Removing based on key and
 * value, will keep from removing duplicate metadata with the same key. It also
 * allows removing all metadata matching key, if needed.
 *
 function delete_comment_meta( $comment_id, $meta_key, $meta_value = '' ) {
 	return delete_metadata( 'comment', $comment_id, $meta_key, $meta_value );
 }
 /**
-* Retrieve comment meta field for a comment.
+* Retrieves comment meta field for a comment.
 *
 * @since 2.9.0
 *
 * @link https://developer.wordpress.org/reference/functions/get_comment_meta/
 *
 function get_comment_meta( $comment_id, $key = '', $single = false ) {
 	return get_metadata( 'comment', $comment_id, $key, $single );
 }
 /**
-* Update comment meta field based on comment ID.
+* Updates comment meta field based on comment ID.
 *
 * Use the $prev_value parameter to differentiate between meta fields with the
 * same key and comment ID.
 *
 * If the meta field for the comment does not exist, it will be added.
 	return $comments_by_type;
 }
 /**
-* Calculate the total number of comment pages.
+* Calculates the total number of comment pages.
 *
 * @since 2.7.0
 *
 * @uses Walker_Comment
 *
 	return $count;
 }
 /**
-* Calculate what page number a comment will appear on for comment paging.
+* Calculates what page number a comment will appear on for comment paging.
 *
 * @since 2.7.0
 *
 * @global wpdb $wpdb WordPress database abstraction object.
 *
 	 * Fires immediately before a comment is deleted from the database.
 	 *
 	 * @since 1.2.0
 	 * @since 4.9.0 Added the `$comment` parameter.
 	 *
-	 * @param int        $comment_id The comment ID.
+	 * @param string     $comment_id The comment ID as a numeric string.
 	 * @param WP_Comment $comment    The comment to be deleted.
 	 */
 	do_action( 'delete_comment', $comment->comment_ID, $comment );
 	// Move children up a level.
 	 * Fires immediately after a comment is deleted from the database.
 	 *
 	 * @since 2.9.0
 	 * @since 4.9.0 Added the `$comment` parameter.
 	 *
-	 * @param int        $comment_id The comment ID.
+	 * @param string     $comment_id The comment ID as a numeric string.
 	 * @param WP_Comment $comment    The deleted comment.
 	 */
 	do_action( 'deleted_comment', $comment->comment_ID, $comment );
 	$post_id = $comment->comment_post_ID;
 	 * Fires immediately before a comment is sent to the Trash.
 	 *
 	 * @since 2.9.0
 	 * @since 4.9.0 Added the `$comment` parameter.
 	 *
-	 * @param int        $comment_id The comment ID.
+	 * @param string     $comment_id The comment ID as a numeric string.
 	 * @param WP_Comment $comment    The comment to be trashed.
 	 */
 	do_action( 'trash_comment', $comment->comment_ID, $comment );
 	if ( wp_set_comment_status( $comment, 'trash' ) ) {
 		 * Fires immediately after a comment is sent to Trash.
 		 *
 		 * @since 2.9.0
 		 * @since 4.9.0 Added the `$comment` parameter.
 		 *
-		 * @param int        $comment_id The comment ID.
+		 * @param string     $comment_id The comment ID as a numeric string.
 		 * @param WP_Comment $comment    The trashed comment.
 		 */
 		do_action( 'trashed_comment', $comment->comment_ID, $comment );
 		return true;
 	 * Fires immediately before a comment is restored from the Trash.
 	 *
 	 * @since 2.9.0
 	 * @since 4.9.0 Added the `$comment` parameter.
 	 *
-	 * @param int        $comment_id The comment ID.
+	 * @param string     $comment_id The comment ID as a numeric string.
 	 * @param WP_Comment $comment    The comment to be untrashed.
 	 */
 	do_action( 'untrash_comment', $comment->comment_ID, $comment );
 	$status = (string) get_comment_meta( $comment->comment_ID, '_wp_trash_meta_status', true );
 		 * Fires immediately after a comment is restored from the Trash.
 		 *
 		 * @since 2.9.0
 		 * @since 4.9.0 Added the `$comment` parameter.
 		 *
-		 * @param int        $comment_id The comment ID.
+		 * @param string     $comment_id The comment ID as a numeric string.
 		 * @param WP_Comment $comment    The untrashed comment.
 		 */
 		do_action( 'untrashed_comment', $comment->comment_ID, $comment );
 		return true;
 	return false;
 }
 /**
-* Marks a comment as Spam
+* Marks a comment as Spam.
 *
 * @since 2.9.0
 *
 * @param int|WP_Comment $comment_id Comment ID or WP_Comment object.
 * @return bool True on success, false on failure.
 	return false;
 }
 /**
-* Removes a comment from the Spam
+* Removes a comment from the Spam.
 *
 * @since 2.9.0
 *
 * @param int|WP_Comment $comment_id Comment ID or WP_Comment object.
 * @return bool True on success, false on failure.
 	 * Fires immediately before a comment is unmarked as Spam.
 	 *
 	 * @since 2.9.0
 	 * @since 4.9.0 Added the `$comment` parameter.
 	 *
-	 * @param int        $comment_id The comment ID.
+	 * @param string     $comment_id The comment ID as a numeric string.
 	 * @param WP_Comment $comment    The comment to be unmarked as spam.
 	 */
 	do_action( 'unspam_comment', $comment->comment_ID, $comment );
 	$status = (string) get_comment_meta( $comment->comment_ID, '_wp_trash_meta_status', true );
 		 * Fires immediately after a comment is unmarked as Spam.
 		 *
 		 * @since 2.9.0
 		 * @since 4.9.0 Added the `$comment` parameter.
 		 *
-		 * @param int        $comment_id The comment ID.
+		 * @param string     $comment_id The comment ID as a numeric string.
 		 * @param WP_Comment $comment    The comment unmarked as spam.
 		 */
 		do_action( 'unspammed_comment', $comment->comment_ID, $comment );
 		return true;
 	return false;
 }
 /**
-* The status of a comment by ID.
+* Retrieves the status of a comment by comment ID.
 *
 * @since 1.0.0
 *
 * @param int|WP_Comment $comment_id Comment ID or WP_Comment object
 * @return string|false Status might be 'trash', 'approved', 'unapproved', 'spam'. False on failure.
 		return false;
 	}
 }
 /**
-* Call hooks for when a comment status transition occurs.
+* Calls hooks for when a comment status transition occurs.
 *
 * Calls hooks for comment status transitions. If the new comment status is not the same
 * as the previous comment status, then two hooks will be ran, the first is
 * {@see 'transition_comment_status'} with new status, old status, and comment data.
 * The next action called is {@see 'comment_$old_status_to_$new_status'}. It has
 		 * Fires when the comment status is in transition from one specific status to another.
 		 *
 		 * The dynamic portions of the hook name, `$old_status`, and `$new_status`,
 		 * refer to the old and new comment statuses, respectively.
 		 *
+		 * Possible hook names include:
+		 *
+		 *  - `comment_unapproved_to_approved`
+		 *  - `comment_spam_to_approved`
+		 *  - `comment_approved_to_unapproved`
+		 *  - `comment_spam_to_unapproved`
+		 *  - `comment_unapproved_to_spam`
+		 *  - `comment_approved_to_spam`
+		 *
 		 * @since 2.7.0
 		 *
 		 * @param WP_Comment $comment Comment object.
 		 */
 		do_action( "comment_{$old_status}_to_{$new_status}", $comment );
 	 * Fires when the status of a specific comment type is in transition.
 	 *
 	 * The dynamic portions of the hook name, `$new_status`, and `$comment->comment_type`,
 	 * refer to the new comment status, and the type of comment, respectively.
 	 *
-	 * Typical comment types include an empty string (standard comment), 'pingback',
+	 * Typical comment types include 'comment', 'pingback', or 'trackback'.
-	 * or 'trackback'.
+	 *
+	 * Possible hook names include:
+	 *
+	 *  - `comment_approved_comment`
+	 *  - `comment_approved_pingback`
+	 *  - `comment_approved_trackback`
+	 *  - `comment_unapproved_comment`
+	 *  - `comment_unapproved_pingback`
+	 *  - `comment_unapproved_trackback`
+	 *  - `comment_spam_comment`
+	 *  - `comment_spam_pingback`
+	 *  - `comment_spam_trackback`
 	 *
 	 * @since 2.7.0
 	 *
-	 * @param int        $comment_ID The comment ID.
+	 * @param string     $comment_ID The comment ID as a numeric string.
 	 * @param WP_Comment $comment    Comment object.
 	 */
 	do_action( "comment_{$new_status}_{$comment->comment_type}", $comment->comment_ID, $comment );
 }
 /**
-* Clear the lastcommentmodified cached value when a comment status is changed.
+* Clears the lastcommentmodified cached value when a comment status is changed.
 *
 * Deletes the lastcommentmodified cache key when a comment enters or leaves
 * 'approved' status.
 *
 * @since 4.7.0
 * @param string $new_status The new comment status.
 * @param string $old_status The old comment status.
 */
 function _clear_modified_cache_on_transition_comment_status( $new_status, $old_status ) {
 	if ( 'approved' === $new_status || 'approved' === $old_status ) {
+		$data = array();
 		foreach ( array( 'server', 'gmt', 'blog' ) as $timezone ) {
-			wp_cache_delete( "lastcommentmodified:$timezone", 'timeinfo' );
+			$data[] = "lastcommentmodified:$timezone";
 		}
-	}
+		wp_cache_delete_multiple( $data, 'timeinfo' );
-}
+	}
+}
-/**
-* Get current commenter's name, email, and URL.
+/**
+* Gets current commenter's name, email, and URL.
 *
 * Expects cookies content to already be sanitized. User of this function might
 * wish to recheck the returned array for validity.
 *
 * @see sanitize_comment_cookies() Use to sanitize cookies
 	 */
 	return apply_filters( 'wp_get_current_commenter', compact( 'comment_author', 'comment_author_email', 'comment_author_url' ) );
 }
 /**
-* Get unapproved comment author's email.
+* Gets unapproved comment author's email.
 *
 * Used to allow the commenter to see their pending comment.
 *
 * @since 5.1.0
 * @since 5.7.0 The window within which the author email for an unapproved comment
 	$id = (int) $wpdb->insert_id;
 	if ( 1 == $comment_approved ) {
 		wp_update_comment_count( $comment_post_ID );
+		$data = array();
 		foreach ( array( 'server', 'gmt', 'blog' ) as $timezone ) {
-			wp_cache_delete( "lastcommentmodified:$timezone", 'timeinfo' );
+			$data[] = "lastcommentmodified:$timezone";
 		}
+		wp_cache_delete_multiple( $data, 'timeinfo' );
 	}
 	clean_comment_cache( $id );
 	$comment = get_comment( $id );
 	$commentdata['filtered']             = true;
 	return $commentdata;
 }
 /**
-* Whether a comment should be blocked because of comment flood.
+* Determines whether a comment should be blocked because of comment flood.
 *
 * @since 2.1.0
 *
 * @param bool $block            Whether plugin has already blocked comment.
 * @param int  $time_lastcomment Timestamp for last comment.
 	return $comment_ID;
 }
 /**
-* Send a comment moderation notification to the comment moderator.
+* Sends a comment moderation notification to the comment moderator.
 *
 * @since 4.4.0
 *
 * @param int $comment_ID ID of the comment.
 * @return bool True on success, false on failure.
 	return wp_notify_moderator( $comment_ID );
 }
 /**
-* Send a notification of a new comment to the post author.
+* Sends a notification of a new comment to the post author.
 *
 * @since 4.4.0
 *
 * Uses the {@see 'notify_post_author'} filter to determine whether the post author
 * should be notified when a new comment is added, overriding site setting.
 	 * Fires immediately after transitioning a comment's status from one to another in the database
 	 * and removing the comment from the object cache, but prior to all status transition hooks.
 	 *
 	 * @since 1.5.0
 	 *
-	 * @param int    $comment_id     Comment ID.
+	 * @param string $comment_id     Comment ID as a numeric string.
 	 * @param string $comment_status Current comment status. Possible values include
 	 *                               'hold', '0', 'approve', '1', 'spam', and 'trash'.
 	 */
 	do_action( 'wp_set_comment_status', $comment->comment_ID, $comment_status );
 	return $rval;
 }
 /**
-* Whether to defer comment counting.
+* Determines whether to defer comment counting.
 *
 * When setting $defer to true, all post comment counts will not be updated
 * until $defer is set to false. When $defer is set to false, then all
 * previously deferred updated post comment counts will then be automatically
 * updated without having to call wp_update_comment_count() after.
 	return false;
 }
 /**
-* Perform all pingbacks, enclosures, trackbacks, and send to pingback services.
+* Performs all pingbacks, enclosures, trackbacks, and sends to pingback services.
 *
 * @since 2.1.0
 * @since 5.6.0 Introduced `do_all_pings` action hook for individual services.
 */
 function do_all_pings() {
 	 */
 	do_action( 'do_all_pings' );
 }
 /**
-* Perform all pingbacks.
+* Performs all pingbacks.
 *
 * @since 5.6.0
 */
 function do_all_pingbacks() {
 	$pings = get_posts(
 		pingback( null, $ping );
 	}
 }
 /**
-* Perform all enclosures.
+* Performs all enclosures.
 *
 * @since 5.6.0
 */
 function do_all_enclosures() {
 	$enclosures = get_posts(
 		do_enclose( null, $enclosure );
 	}
 }
 /**
-* Perform all trackbacks.
+* Performs all trackbacks.
 *
 * @since 5.6.0
 */
 function do_all_trackbacks() {
 	$trackbacks = get_posts(
 		do_trackbacks( $trackback );
 	}
 }
 /**
-* Perform trackbacks.
+* Performs trackbacks.
 *
 * @since 1.5.0
 * @since 4.7.0 `$post_id` can be a WP_Post object.
 *
 * @global wpdb $wpdb WordPress database abstraction object.
 		}
 	}
 }
 /**
-* Check whether blog is public before returning sites.
+* Checks whether blog is public before returning sites.
 *
 * @since 2.1.0
 *
 * @param mixed $sites Will return if blog is public, will not return if not public.
 * @return mixed Empty string if blog is not public, returns $sites, if site is public.
 		return '';
 	}
 }
 /**
-* Send a Trackback.
+* Sends a Trackback.
 *
 * Updates database when sending trackback to prevent duplicates.
 *
 * @since 0.71
 *
 	$wpdb->query( $wpdb->prepare( "UPDATE $wpdb->posts SET pinged = CONCAT(pinged, '\n', %s) WHERE ID = %d", $trackback_url, $ID ) );
 	return $wpdb->query( $wpdb->prepare( "UPDATE $wpdb->posts SET to_ping = TRIM(REPLACE(to_ping, %s, '')) WHERE ID = %d", $trackback_url, $ID ) );
 }
 /**
-* Send a pingback.
+* Sends a pingback.
 *
 * @since 1.2.0
 *
 * @param string $server Host of blog to connect to.
 * @param string $path Path to send the ping.
 		$client->query( 'weblogUpdates.ping', get_option( 'blogname' ), $home );
 	}
 }
 /**
-* Default filter attached to pingback_ping_source_uri to validate the pingback's Source URI
+* Default filter attached to pingback_ping_source_uri to validate the pingback's Source URI.
 *
 * @since 3.5.1
 *
 * @see wp_http_validate_url()
 *
 * @since 2.3.0
 *
 * @param int|array $ids Comment ID or an array of comment IDs to remove from cache.
 */
 function clean_comment_cache( $ids ) {
-	foreach ( (array) $ids as $id ) {
+	$comment_ids = (array) $ids;
-		wp_cache_delete( $id, 'comment' );
+	wp_cache_delete_multiple( $comment_ids, 'comment' );
+	foreach ( $comment_ids as $id ) {
 		/**
 		 * Fires immediately after a comment has been removed from the object cache.
 		 *
 		 * @since 4.5.0
 		 *
 *
 * @param WP_Comment[] $comments          Array of comment objects
 * @param bool         $update_meta_cache Whether to update commentmeta cache. Default true.
 */
 function update_comment_cache( $comments, $update_meta_cache = true ) {
+	$data = array();
 	foreach ( (array) $comments as $comment ) {
-		wp_cache_add( $comment->comment_ID, $comment, 'comment' );
+		$data[ $comment->comment_ID ] = $comment;
 	}
+	wp_cache_add_multiple( $data, 'comment' );
 	if ( $update_meta_cache ) {
 		// Avoid `wp_list_pluck()` in case `$comments` is passed by reference.
 		$comment_ids = array();
 		foreach ( $comments as $comment ) {
 //
 // Internal.
 //
 /**
-* Close comments on old posts on the fly, without any extra DB queries. Hooked to the_posts.
+* Closes comments on old posts on the fly, without any extra DB queries. Hooked to the_posts.
 *
 * @since 2.7.0
 * @access private
 *
 * @param WP_Post  $posts Post data object.
 	return $posts;
 }
 /**
-* Close comments on an old post. Hooked to comments_open and pings_open.
+* Closes comments on an old post. Hooked to comments_open and pings_open.
 *
 * @since 2.7.0
 * @access private
 *
 * @param bool $open    Comments open or closed.
 	$comment_type = 'comment';
 	if ( get_option( 'require_name_email' ) && ! $user->exists() ) {
 		if ( '' == $comment_author_email || '' == $comment_author ) {
-			return new WP_Error( 'require_name_email', __( '<strong>Error</strong>: Please fill the required fields (name, email).' ), 200 );
+			return new WP_Error( 'require_name_email', __( '<strong>Error</strong>: Please fill the required fields.' ), 200 );
 		} elseif ( ! is_email( $comment_author_email ) ) {
 			return new WP_Error( 'require_valid_email', __( '<strong>Error</strong>: Please enter a valid email address.' ), 200 );
 		}
 	}

changeset 19	3d72ae0968f4
parent 18	be944660c56a
child 21	48c4eec2b7e6