Introduce `WP_Comment` class to model/strongly-type rows from the comments database table. Inclusion of this class is a pre-req for some more general comment cleanup and sanity.

* Takes inspiration from `WP_Post` and adds sanity to comment caching. 
* Clarifies when the current global value for `$comment` is returned. The current implementation in `get_comment()` introduces side effects and an occasion stale global value for `$comment` when comment caches are cleaned.
* Strongly-types `@param` docs
* This class is marked `final` for now

Props wonderboymusic, nacin.

See #32619.

Built from https://develop.svn.wordpress.org/trunk@33891


git-svn-id: http://core.svn.wordpress.org/trunk@33860 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-admin/edit-form-comment.php

@@ -171,7 +171,7 @@ do_action( 'add_meta_boxes', 'comment', $comment );
  *
  * @since 3.0.0
  *
- * @param object $comment Comment object.
+ * @param WP_Comment $comment Comment object.
  */
 do_action( 'add_meta_boxes_comment', $comment );
 

wp-admin/includes/comment.php

@@ -74,12 +74,12 @@ function edit_comment() {
 }
 
 /**
- * Returns a comment object based on comment ID.
+ * Returns a WP_Comment object based on comment ID.
  *
  * @since 2.0.0
  *
  * @param int $id ID of comment to retrieve.
- * @return object|false Comment if found. False on failure.
+ * @return WP_Comment|false Comment if found. False on failure.
  */
 function get_comment_to_edit( $id ) {
 	if ( !$comment = get_comment($id) )

wp-admin/includes/dashboard.php

@@ -548,10 +548,10 @@ function wp_dashboard_recent_drafts( $drafts = false ) {
 }
 
 /**
- * @global object $comment
+ * @global WP_Comment $comment
  *
- * @param object $comment
+ * @param WP_Comment $comment
- * @param bool   $show_date
+ * @param bool       $show_date
  */
 function _wp_dashboard_recent_comments_row( &$comment, $show_date = true ) {
 	$GLOBALS['comment'] =& $comment;
@@ -603,10 +603,10 @@ function _wp_dashboard_recent_comments_row( &$comment, $show_date = true ) {
 		 *
 		 * @since 2.6.0
 		 *
-		 * @param array  $actions An array of comment actions. Default actions include:
+		 * @param array      $actions An array of comment actions. Default actions include:
-		 *                        'Approve', 'Unapprove', 'Edit', 'Reply', 'Spam',
+		 *                            'Approve', 'Unapprove', 'Edit', 'Reply', 'Spam',
-		 *                        'Delete', and 'Trash'.
+		 *                            'Delete', and 'Trash'.
-		 * @param object $comment The comment object.
+		 * @param WP_Comment $comment The comment object.
 		 */
 		$actions = apply_filters( 'comment_row_actions', array_filter($actions), $comment );
 

wp-admin/includes/export.php

@@ -473,7 +473,8 @@ function export_wp( $args = array() ) {
 		</wp:postmeta>
 <?php	endforeach;
 
-		$comments = $wpdb->get_results( $wpdb->prepare( "SELECT * FROM $wpdb->comments WHERE comment_post_ID = %d AND comment_approved <> 'spam'", $post->ID ) );
+		$_comments = $wpdb->get_results( $wpdb->prepare( "SELECT * FROM $wpdb->comments WHERE comment_post_ID = %d AND comment_approved <> 'spam'", $post->ID ) );
+		$comments = array_map( 'get_comment', $_comments );
 		foreach ( $comments as $c ) : ?>
 		<wp:comment>
 			<wp:comment_id><?php echo $c->comment_ID; ?></wp:comment_id>

wp-admin/includes/template.php

@@ -743,8 +743,8 @@ function meta_form( $post = null ) {
  *
  * @since 0.71
  *
- * @global WP_Locale $wp_locale
+ * @global WP_Locale  $wp_locale
- * @global object    $comment
+ * @global WP_Comment $comment
  *
  * @param int|bool $edit      Accepts 1|true for editing the date, 0|false for adding the date.
  * @param int|bool $for_post  Accepts 1|true for applying the date to a post, 0|false for a comment.

wp-comments-post.php

@@ -146,8 +146,8 @@ $comment = get_comment( $comment_id );
  *
  * @since 3.4.0
  *
- * @param object $comment Comment object.
+ * @param WP_Comment $comment Comment object.
- * @param WP_User $user   User object. The user may not exist.
+ * @param WP_User    $user    User object. The user may not exist.
  */
 do_action( 'set_comment_cookies', $comment, $user );
 
@@ -158,8 +158,8 @@ $location = empty($_POST['redirect_to']) ? get_comment_link($comment_id) : $_POS
  *
  * @since 2.0.5
  *
- * @param string $location The 'redirect_to' URI sent via $_POST.
+ * @param string     $location The 'redirect_to' URI sent via $_POST.
- * @param object $comment  Comment object.
+ * @param WP_Comment $comment  Comment object.
  */
 $location = apply_filters( 'comment_post_redirect', $location, $comment );
 

wp-includes/class-wp-comment-query.php

@@ -665,7 +665,10 @@ class WP_Comment_Query {
 		 * @param array            $results  An array of comments.
 		 * @param WP_Comment_Query &$this    Current instance of WP_Comment_Query, passed by reference.
 		 */
-		$comments = apply_filters_ref_array( 'the_comments', array( $results, &$this ) );
+		$_comments = apply_filters_ref_array( 'the_comments', array( $results, &$this ) );
+
+		// Convert to WP_Comment instances
+		$comments = array_map( 'get_comment', $_comments );
 
 		wp_cache_add( $cache_key, $comments, 'comment' );
 		if ( '*' === $fields ) {

wp-includes/class-wp-comment.php

@@ -0,0 +1,118 @@
+<?php
+
+ /**
+ * WordPress Comment class
+ *
+ * @since 4.4.0
+ */
+final class WP_Comment {
+	/**
+	 * @var int
+	 */
+	public $comment_ID;
+	/**
+	 * @var int
+	 */
+	public $comment_post_ID = 0;
+	/**
+	 * @var int
+	 */
+	public $comment_author;
+	/**
+	 * @var string
+	 */
+	public $comment_author_email = '';
+	/**
+	 * @var string
+	 */
+	public $comment_author_url = '';
+	/**
+	 * @var string
+	 */
+	public $comment_author_IP = '';
+	/**
+	 * @var string
+	 */
+	public $comment_date = '0000-00-00 00:00:00';
+	/**
+	 * @var string
+	 */
+	public $comment_date_gmt = '0000-00-00 00:00:00';
+	/**
+	 * @var string
+	 */
+	public $comment_content;
+	/**
+	 * @var int
+	 */
+	public $comment_karma = 0;
+	/**
+	 * @var string
+	 */
+	public $comment_approved = '1';
+	/**
+	 * @var string
+	 */
+	public $comment_agent = '';
+	/**
+	 * @var string
+	 */
+	public $comment_type = '';
+	/**
+	 * @var int
+	 */
+	public $comment_parent = 0;
+	/**
+	 * @var int
+	 */
+	public $user_id = 0;
+
+	/**
+	 * Retrieve WP_Comment instance.
+	 *
+	 * @static
+	 * @access public
+	 *
+	 * @global wpdb $wpdb
+	 *
+	 * @param int $id Comment ID.
+	 * @return WP_Comment|false Comment object, false otherwise.
+	 */
+	public static function get_instance( $id ) {
+		global $wpdb;
+
+		$comment_id = (int) $id;
+		if ( ! $comment_id ) {
+			return false;
+		}
+
+		$_comment = wp_cache_get( $comment_id, 'comment' );
+
+		if ( ! $_comment ) {
+			$_comment = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->comments WHERE comment_ID = %d LIMIT 1", $comment_id ) );
+
+			if ( ! $_comment ) {
+				return false;
+			}
+
+			wp_cache_add( $_comment->comment_ID, $_comment, 'comment' );
+		}
+
+		return new WP_Comment( $_comment );
+	}
+
+	/**
+	 * Constructor.
+	 *
+	 * @param WP_Comment $comment Comment object.
+	 */
+	public function __construct( $comment ) {
+		foreach ( get_object_vars( $comment ) as $key => $value ) {
+			$this->$key = $value;
+		}
+	}
+
+	public function to_array() {
+		return get_object_vars( $this );
+	}
+}

wp-includes/class-wp-xmlrpc-server.php

@@ -1042,8 +1042,8 @@ class wp_xmlrpc_server extends IXR_Server {
 		 *
 		 * @since 3.4.0
 		 *
-		 * @param array  $_comment An array of prepared comment data.
+		 * @param array      $_comment An array of prepared comment data.
-		 * @param object $comment  Comment object.
+		 * @param WP_Comment $comment  Comment object.
 		 */
 		return apply_filters( 'xmlrpc_prepare_comment', $_comment, $comment );
 	}

wp-includes/comment-functions.php

@@ -164,30 +164,25 @@ function get_approved_comments( $post_id, $args = array() ) {
  * @global wpdb   $wpdb WordPress database abstraction object.
  * @global object $comment
  *
- * @param object|string|int $comment Comment to retrieve.
+ * @param WP_Comment|string|int $comment Comment to retrieve.
  * @param string $output Optional. OBJECT or ARRAY_A or ARRAY_N constants.
- * @return object|array|null Depends on $output value.
+ * @return WP_Comment|array|null Depends on $output value.
  */
 function get_comment(&$comment, $output = OBJECT) {
-	global $wpdb;
+	if ( empty( $comment ) && isset( $GLOBALS['comment'] ) ) {
+		$comment = $GLOBALS['comment'];
+	}
 
-	if ( empty($comment) ) {
+	if ( $comment instanceof WP_Comment ) {
-		if ( isset($GLOBALS['comment']) )
-			$_comment = & $GLOBALS['comment'];
-		else
-			$_comment = null;
-	} elseif ( is_object($comment) ) {
-		wp_cache_add($comment->comment_ID, $comment, 'comment');
 		$_comment = $comment;
+	} elseif ( is_object( $comment ) ) {
+		$_comment = new WP_Comment( $comment );
 	} else {
-		if ( isset($GLOBALS['comment']) && ($GLOBALS['comment']->comment_ID == $comment) ) {
+		$_comment = WP_Comment::get_instance( $comment );
-			$_comment = & $GLOBALS['comment'];
+	}
-		} elseif ( ! $_comment = wp_cache_get($comment, 'comment') ) {
+
-			$_comment = $wpdb->get_row($wpdb->prepare("SELECT * FROM $wpdb->comments WHERE comment_ID = %d LIMIT 1", $comment));
+	if ( ! $_comment ) {
-			if ( ! $_comment )
+		return null;
-				return null;
-			wp_cache_add($_comment->comment_ID, $_comment, 'comment');
-		}
 	}
 
 	/**
@@ -202,14 +197,11 @@ function get_comment(&$comment, $output = OBJECT) {
 	if ( $output == OBJECT ) {
 		return $_comment;
 	} elseif ( $output == ARRAY_A ) {
-		$__comment = get_object_vars($_comment);
+		return $_comment->to_array();
-		return $__comment;
 	} elseif ( $output == ARRAY_N ) {
-		$__comment = array_values(get_object_vars($_comment));
+		return array_values( $_comment->to_array() );
-		return $__comment;
-	} else {
-		return $_comment;
 	}
+	return $_comment;
 }
 
 /**
@@ -479,8 +471,8 @@ function update_comment_meta($comment_id, $meta_key, $meta_value, $prev_value =
  * Sets the cookies used to store an unauthenticated commentator's identity. Typically used
  * to recall previous comments by this commentator that are still held in moderation.
  *
- * @param object $comment Comment object.
+ * @param WP_Comment $comment Comment object.
- * @param object $user Comment author's object.
+ * @param object     $user    Comment author's object.
  *
  * @since 3.4.0
  */
@@ -760,7 +752,7 @@ function separate_comments(&$comments) {
  *
  * @global WP_Query $wp_query
  *
- * @param array $comments Optional array of comment objects. Defaults to $wp_query->comments
+ * @param array $comments Optional array of WP_Comment objects. Defaults to $wp_query->comments
  * @param int   $per_page Optional comments per page.
  * @param bool  $threaded Optional control over flat or threaded comments.
  * @return int Number of comment pages.
@@ -1288,7 +1280,7 @@ function wp_transition_comment_status($new_status, $old_status, $comment) {
 		 *
 		 * @since 2.7.0
 		 *
-		 * @param object $comment Comment object.
+		 * @param WP_Comment $comment Comment object.
 		 */
 		do_action( "comment_{$old_status}_to_{$new_status}", $comment );
 	}
@@ -1303,8 +1295,8 @@ function wp_transition_comment_status($new_status, $old_status, $comment) {
 	 *
 	 * @since 2.7.0
 	 *
-	 * @param int $comment_ID The comment ID.
+	 * @param int        $comment_ID The comment ID.
-	 * @param obj $comment    Comment object.
+	 * @param WP_Comment $comment    Comment object.
 	 */
 	do_action( "comment_{$new_status}_{$comment->comment_type}", $comment->comment_ID, $comment );
 }
@@ -1423,8 +1415,8 @@ function wp_insert_comment( $commentdata ) {
 	 *
 	 * @since 2.8.0
 	 *
-	 * @param int $id      The comment ID.
+	 * @param int        $id      The comment ID.
-	 * @param obj $comment Comment object.
+	 * @param WP_Comment $comment Comment object.
 	 */
 	do_action( 'wp_insert_comment', $id, $comment );
 

wp-includes/comment-template.php

@@ -37,9 +37,9 @@ function get_comment_author( $comment_ID = 0 ) {
 	 * @since 1.5.0
 	 * @since 4.1.0 The `$comment_ID` and `$comment` parameters were added.
 	 *
-	 * @param string $author     The comment author's username.
+	 * @param string     $author     The comment author's username.
-	 * @param int    $comment_ID The comment ID.
+	 * @param int        $comment_ID The comment ID.
-	 * @param object $comment    The comment object.
+	 * @param WP_Comment $comment    The comment object.
 	 */
 	return apply_filters( 'get_comment_author', $author, $comment_ID, $comment );
 }
@@ -83,9 +83,9 @@ function get_comment_author_email( $comment_ID = 0 ) {
 	 * @since 1.5.0
 	 * @since 4.1.0 The `$comment_ID` and `$comment` parameters were added.
 	 *
-	 * @param string $comment_author_email The comment author's email address.
+	 * @param string     $comment_author_email The comment author's email address.
-	 * @param int    $comment_ID           The comment ID.
+	 * @param int        $comment_ID           The comment ID.
-	 * @param object $comment              The comment object.
+	 * @param WP_Comment $comment              The comment object.
 	 */
 	return apply_filters( 'get_comment_author_email', $comment->comment_author_email, $comment_ID, $comment );
 }
@@ -170,8 +170,8 @@ function get_comment_author_email_link( $linktext = '', $before = '', $after = '
 	 * @since 1.2.0
 	 * @since 4.1.0 The `$comment` parameter was added.
 	 *
-	 * @param string $comment_author_email The comment author's email address.
+	 * @param string     $comment_author_email The comment author's email address.
-	 * @param object $comment              The comment object.
+	 * @param WP_Comment $comment              The comment object.
 	 */
 	$email = apply_filters( 'comment_email', $comment->comment_author_email, $comment );
 	if ((!empty($email)) && ($email != '@')) {
@@ -250,9 +250,9 @@ function get_comment_author_IP( $comment_ID = 0 ) {
 	 * @since 1.5.0
 	 * @since 4.1.0 The `$comment_ID` and `$comment` parameters were added.
 	 *
-	 * @param string $comment_author_IP The comment author's IP address.
+	 * @param string     $comment_author_IP The comment author's IP address.
-	 * @param int    $comment_ID        The comment ID.
+	 * @param int        $comment_ID        The comment ID.
-	 * @param object $comment           The comment object.
+	 * @param WP_Comment $comment           The comment object.
 	 */
 	return apply_filters( 'get_comment_author_IP', $comment->comment_author_IP, $comment_ID, $comment );
 }
@@ -289,9 +289,9 @@ function get_comment_author_url( $comment_ID = 0 ) {
 	 * @since 1.5.0
 	 * @since 4.1.0 The `$comment_ID` and `$comment` parameters were added.
 	 *
-	 * @param string $url        The comment author's URL.
+	 * @param string     $url        The comment author's URL.
-	 * @param int    $comment_ID The comment ID.
+	 * @param int        $comment_ID The comment ID.
-	 * @param object $comment    The comment object.
+	 * @param WP_Comment $comment    The comment object.
 	 */
 	return apply_filters( 'get_comment_author_url', $url, $comment_ID, $comment );
 }
@@ -508,7 +508,7 @@ function get_comment_date( $d = '', $comment_ID = 0 ) {
 	 *
 	 * @param string|int $date    Formatted date string or Unix timestamp.
 	 * @param string     $d       The format of the date.
-	 * @param object     $comment The comment object.
+	 * @param WP_Comment $comment The comment object.
 	 */
 	return apply_filters( 'get_comment_date', $date, $d, $comment );
 }
@@ -563,9 +563,9 @@ function get_comment_excerpt( $comment_ID = 0 ) {
 	 * @since 1.5.0
 	 * @since 4.1.0 The `$comment_ID` and `$comment` parameters were added.
 	 *
-	 * @param string $excerpt    The comment excerpt text.
+	 * @param string     $excerpt    The comment excerpt text.
-	 * @param int    $comment_ID The comment ID.
+	 * @param int        $comment_ID The comment ID.
-	 * @param object $comment    The comment object.
+	 * @param WP_Comment $comment    The comment object.
 	 */
 	return apply_filters( 'get_comment_excerpt', $excerpt, $comment_ID, $comment );
 }
@@ -611,8 +611,8 @@ function get_comment_ID() {
 	 * @since 1.5.0
 	 * @since 4.1.0 The `$comment_ID` parameter was added.
 	 *
-	 * @param int    $comment_ID The current comment ID.
+	 * @param int        $comment_ID The current comment ID.
-	 * @param object $comment    The comment object.
+	 * @param WP_Comment $comment    The comment object.
 	 */
 	return apply_filters( 'get_comment_ID', $comment->comment_ID, $comment );
 }
@@ -636,8 +636,8 @@ function comment_ID() {
  * @global WP_Rewrite $wp_rewrite
  * @global bool       $in_comment_loop
  *
- * @param mixed $comment Comment to retrieve. Default current comment.
+ * @param WP_Comment|int|null $comment Comment to retrieve. Default current comment.
- * @param array $args    Optional. An array of arguments to override the defaults.
+ * @param array               $args    Optional. An array of arguments to override the defaults.
  * @return string The permalink to the given comment.
  */
 function get_comment_link( $comment = null, $args = array() ) {
@@ -681,9 +681,9 @@ function get_comment_link( $comment = null, $args = array() ) {
 	 *
 	 * @see get_page_of_comment()
 	 *
-	 * @param string $link    The comment permalink with '#comment-$id' appended.
+	 * @param string     $link    The comment permalink with '#comment-$id' appended.
-	 * @param object $comment The current comment object.
+	 * @param WP_Comment $comment The current comment object.
-	 * @param array  $args    An array of arguments to override the defaults.
+	 * @param array      $args    An array of arguments to override the defaults.
 	 */
 	return apply_filters( 'get_comment_link', $link, $comment, $args );
 }
@@ -825,9 +825,9 @@ function get_comment_text( $comment_ID = 0, $args = array() ) {
 	 *
 	 * @see Walker_Comment::comment()
 	 *
-	 * @param string $comment_content Text of the comment.
+	 * @param string     $comment_content Text of the comment.
-	 * @param object $comment         The comment object.
+	 * @param WP_Comment $comment         The comment object.
-	 * @param array  $args            An array of arguments.
+	 * @param array      $args            An array of arguments.
 	 */
 	return apply_filters( 'get_comment_text', $comment->comment_content, $comment, $args );
 }
@@ -853,9 +853,9 @@ function comment_text( $comment_ID = 0, $args = array() ) {
 	 *
 	 * @see Walker_Comment::comment()
 	 *
-	 * @param string $comment_text Text of the current comment.
+	 * @param string     $comment_text Text of the current comment.
-	 * @param object $comment      The comment object.
+	 * @param WP_Comment $comment      The comment object.
-	 * @param array  $args         An array of arguments.
+	 * @param array      $args         An array of arguments.
 	 */
 	echo apply_filters( 'comment_text', $comment_text, $comment, $args );
 }
@@ -890,7 +890,7 @@ function get_comment_time( $d = '', $gmt = false, $translate = true ) {
 	 * @param string     $d         Date format.
 	 * @param bool       $gmt       Whether the GMT date is in use.
 	 * @param bool       $translate Whether the time is translated.
-	 * @param object     $comment   The comment object.
+	 * @param WP_Comment $comment   The comment object.
 	 */
 	return apply_filters( 'get_comment_time', $date, $d, $gmt, $translate, $comment );
 }
@@ -925,9 +925,9 @@ function get_comment_type( $comment_ID = 0 ) {
 	 * @since 1.5.0
 	 * @since 4.1.0 The `$comment_ID` and `$comment` parameters were added.
 	 *
-	 * @param string $comment_type The type of comment, such as 'comment', 'pingback', or 'trackback'.
+	 * @param string     $comment_type The type of comment, such as 'comment', 'pingback', or 'trackback'.
-	 * @param int 	 $comment_ID   The comment ID.
+	 * @param int 	     $comment_ID   The comment ID.
-	 * @param object $comment      The comment object.
+	 * @param WP_Comment $comment      The comment object.
 	 */
 	return apply_filters( 'get_comment_type', $comment->comment_type, $comment_ID, $comment );
 }
@@ -1858,10 +1858,10 @@ class Walker_Comment extends Walker {
 	 * @see Walker::end_el()
 	 * @see wp_list_comments()
 	 *
-	 * @param string $output  Passed by reference. Used to append additional content.
+	 * @param string     $output  Passed by reference. Used to append additional content.
-	 * @param object $comment The comment object. Default current comment.
+	 * @param WP_Comment $comment The comment object. Default current comment.
-	 * @param int    $depth   Depth of comment.
+	 * @param int        $depth   Depth of comment.
-	 * @param array  $args    An array of arguments.
+	 * @param array      $args    An array of arguments.
 	 */
 	public function end_el( &$output, $comment, $depth = 0, $args = array() ) {
 		if ( !empty( $args['end-callback'] ) ) {
@@ -1884,9 +1884,9 @@ class Walker_Comment extends Walker {
 	 *
 	 * @see wp_list_comments()
 	 *
-	 * @param object $comment The comment object.
+	 * @param WP_Comment $comment The comment object.
-	 * @param int    $depth   Depth of comment.
+	 * @param int        $depth   Depth of comment.
-	 * @param array  $args    An array of arguments.
+	 * @param array      $args    An array of arguments.
 	 */
 	protected function ping( $comment, $depth, $args ) {
 		$tag = ( 'div' == $args['style'] ) ? 'div' : 'li';
@@ -2048,7 +2048,7 @@ class Walker_Comment extends Walker {
  *     @type bool   $short_ping        Whether to output short pings. Default false.
  *     @type bool   $echo              Whether to echo the output or return it. Default true.
  * }
- * @param array $comments Optional. Array of comment objects.
+ * @param array $comments Optional. Array of WP_Comment objects.
  */
 function wp_list_comments( $args = array(), $comments = null ) {
 	global $wp_query, $comment_alt, $comment_depth, $comment_thread_alt, $overridden_cpage, $in_comment_loop;

wp-includes/comment.php

@@ -6,5 +6,6 @@
  * @subpackage Comment
  */
 
+require_once( ABSPATH . WPINC . '/class-wp-comment.php' );
 require_once( ABSPATH . WPINC . '/class-wp-comment-query.php' );
 require_once( ABSPATH . WPINC . '/comment-functions.php' );

wp-includes/feed.php

@@ -264,7 +264,8 @@ function comments_link_feed() {
  *
  * @since 2.5.0
  *
- * @param int|object $comment_id Optional comment object or id. Defaults to global comment object.
+ * @param mixed  $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
+ *                            user email, WP_User object, WP_Post object, or WP_Comment object.
  */
 function comment_guid($comment_id = null) {
 	echo esc_url( get_comment_guid($comment_id) );
@@ -275,7 +276,8 @@ function comment_guid($comment_id = null) {
  *
  * @since 2.5.0
  *
- * @param int|object $comment_id Optional comment object or id. Defaults to global comment object.
+ * @param mixed  $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
+ *                            user email, WP_User object, WP_Post object, or WP_Comment object.
  * @return false|string false on failure or guid for comment on success.
  */
 function get_comment_guid($comment_id = null) {

wp-includes/link-template.php

@@ -3454,7 +3454,7 @@ function the_shortlink( $text = '', $title = '', $before = '', $after = '' ) {
  * @since 4.2.0
  *
  * @param mixed $id_or_email The Gravatar to retrieve a URL for. Accepts a user_id, gravatar md5 hash,
- *                           user email, WP_User object, WP_Post object, or comment object.
+ *                           user email, WP_User object, WP_Post object, or WP_Comment object.
  * @param array $args {
  *     Optional. Arguments to return instead of the default arguments.
  *
@@ -3485,8 +3485,8 @@ function get_avatar_url( $id_or_email, $args = null ) {
  *
  * @since 4.2.0
  *
- * @param mixed $id_or_email The Gravatar to check the data against. Accepts a user_id, gravatar md5 hash,
+ * @param mixed $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
- *                           user email, WP_User object, WP_Post object, or comment object.
+ *                            user email, WP_User object, WP_Post object, or WP_Comment object.
  * @param array $args {
  *     Optional. Arguments to return instead of the default arguments.
  *
@@ -3586,8 +3586,9 @@ function get_avatar_data( $id_or_email, $args = null ) {
 	 *
 	 * @since 4.2.0
 	 *
-	 * @param array             $args          Arguments passed to get_avatar_data(), after processing.
+	 * @param array  $args        Arguments passed to get_avatar_data(), after processing.
-	 * @param int|object|string $id_or_email   A user ID, email address, or comment object.
+	 * @param mixed  $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
+	 *                            user email, WP_User object, WP_Post object, or WP_Comment object.
 	 */
 	$args = apply_filters( 'pre_get_avatar_data', $args, $id_or_email );
 
@@ -3616,9 +3617,7 @@ function get_avatar_data( $id_or_email, $args = null ) {
 	} elseif ( $id_or_email instanceof WP_Post ) {
 		// Post Object
 		$user = get_user_by( 'id', (int) $id_or_email->post_author );
-	} elseif ( is_object( $id_or_email ) && isset( $id_or_email->comment_ID ) ) {
+	} elseif ( $id_or_email instanceof WP_Comment ) {
-		// Comment Object
-
 		/**
 		 * Filter the list of allowed comment types for retrieving avatars.
 		 *
@@ -3681,9 +3680,10 @@ function get_avatar_data( $id_or_email, $args = null ) {
 	 *
 	 * @since 4.2.0
 	 *
-	 * @param string            $url         The URL of the avatar.
+	 * @param string $url         The URL of the avatar.
-	 * @param int|object|string $id_or_email A user ID, email address, or comment object.
+	 * @param mixed  $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
-	 * @param array             $args        Arguments passed to get_avatar_data(), after processing.
+	 *                            user email, WP_User object, WP_Post object, or WP_Comment object.
+	 * @param array  $args        Arguments passed to get_avatar_data(), after processing.
 	 */
 	$args['url'] = apply_filters( 'get_avatar_url', $url, $id_or_email, $args );
 
@@ -3692,8 +3692,9 @@ function get_avatar_data( $id_or_email, $args = null ) {
 	 *
 	 * @since 4.2.0
 	 *
-	 * @param array             $args        Arguments passed to get_avatar_data(), after processing.
+	 * @param array  $args        Arguments passed to get_avatar_data(), after processing.
-	 * @param int|object|string $id_or_email A user ID, email address, or comment object.
+	 * @param mixed  $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
+	 *                            user email, WP_User object, WP_Post object, or WP_Comment object.
 	 */
 	return apply_filters( 'get_avatar_data', $args, $id_or_email );
 }

wp-includes/pluggable.php

@@ -2190,7 +2190,7 @@ if ( !function_exists( 'get_avatar' ) ) :
  * @since 4.2.0 Optional `$args` parameter added.
  *
  * @param mixed $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
- *                           user email, WP_User object, WP_Post object, or comment object.
+ *                           user email, WP_User object, WP_Post object, or WP_Comment object.
  * @param int    $size       Optional. Height and width of the avatar image file in pixels. Default 96.
  * @param string $default    Optional. URL for the default image or a default type. Accepts '404'
  *                           (return a 404 instead of a default image), 'retro' (8bit), 'monsterid'
@@ -2258,9 +2258,10 @@ function get_avatar( $id_or_email, $size = 96, $default = '', $alt = '', $args =
 	 *
 	 * @since 4.2.0
 	 *
-	 * @param string            $avatar      HTML for the user's avatar. Default null.
+	 * @param string $avatar      HTML for the user's avatar. Default null.
-	 * @param int|object|string $id_or_email A user ID, email address, or comment object.
+	 * @param mixed  $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
-	 * @param array             $args        Arguments passed to get_avatar_url(), after processing.
+	 *                            user email, WP_User object, WP_Post object, or WP_Comment object.
+	 * @param array  $args        Arguments passed to get_avatar_url(), after processing.
 	 */
 	$avatar = apply_filters( 'pre_get_avatar', null, $id_or_email, $args );
 
@@ -2314,12 +2315,13 @@ function get_avatar( $id_or_email, $size = 96, $default = '', $alt = '', $args =
 	 * @since 2.5.0
 	 * @since 4.2.0 The `$args` parameter was added.
 	 *
-	 * @param string            $avatar      <img> tag for the user's avatar.
+	 * @param string $avatar      <img> tag for the user's avatar.
-	 * @param int|object|string $id_or_email A user ID, email address, or comment object.
+	 * @param mixed  $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
-	 * @param int               $size        Square avatar width and height in pixels to retrieve.
+	 *                            user email, WP_User object, WP_Post object, or WP_Comment object.
-	 * @param string            $alt         Alternative text to use in the avatar image tag.
+	 * @param int    $size        Square avatar width and height in pixels to retrieve.
+	 * @param string $alt         Alternative text to use in the avatar image tag.
 	 *                                       Default empty.
-	 * @param array             $args        Arguments passed to get_avatar_data(), after processing.
+	 * @param array  $args        Arguments passed to get_avatar_data(), after processing.
 	 */
 	return apply_filters( 'get_avatar', $avatar, $id_or_email, $args['size'], $args['default'], $args['alt'], $args );
 }

wp-includes/query.php

@@ -3186,7 +3186,9 @@ class WP_Query {
 			$cgroupby = ( ! empty( $cgroupby ) ) ? 'GROUP BY ' . $cgroupby : '';
 			$corderby = ( ! empty( $corderby ) ) ? 'ORDER BY ' . $corderby : '';
 
-			$this->comments = (array) $wpdb->get_results("SELECT $distinct $wpdb->comments.* FROM $wpdb->comments $cjoin $cwhere $cgroupby $corderby $climits");
+			$comments = (array) $wpdb->get_results("SELECT $distinct $wpdb->comments.* FROM $wpdb->comments $cjoin $cwhere $cgroupby $corderby $climits");
+			// Convert to WP_Comment
+			$this->comments = array_map( 'get_comment', $comments );
 			$this->comment_count = count($this->comments);
 
 			$post_ids = array();
@@ -3557,7 +3559,9 @@ class WP_Query {
 			$climits = apply_filters_ref_array( 'comment_feed_limits', array( 'LIMIT ' . get_option('posts_per_rss'), &$this ) );
 
 			$comments_request = "SELECT $wpdb->comments.* FROM $wpdb->comments $cjoin $cwhere $cgroupby $corderby $climits";
-			$this->comments = $wpdb->get_results($comments_request);
+			$comments = $wpdb->get_results($comments_request);
+			// Convert to WP_Comment
+			$this->comments = array_map( 'get_comment', $comments );
 			$this->comment_count = count($this->comments);
 		}
 
@@ -3812,12 +3816,12 @@ class WP_Query {
 	}
 
 	/**
-	 * Iterate current comment index and return comment object.
+	 * Iterate current comment index and return WP_Comment object.
 	 *
 	 * @since 2.2.0
 	 * @access public
 	 *
-	 * @return object Comment object.
+	 * @return WP_Comment Comment object.
 	 */
 	public function next_comment() {
 		$this->current_comment++;

wp-includes/version.php

@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '4.4-alpha-33890';
+$wp_version = '4.4-alpha-33891';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.