Introduce hierarchical query support to WP_Comment_Query.

Comments can be threaded. Now your query can be threaded too! Bonus: it's
not totally insane.

* The new `$hierarchical` parameter for `WP_Comment_Query` accepts three values:
  * `false` - Default value, and equivalent to current behavior. No descendants are fetched for matched comments.
  * `'flat'` - `WP_Comment_Query` will fetch the descendant tree for each comment matched by the query paramaters, and append them to the flat array of comments returned. Use this when you have a separate routine for constructing the tree - for example, when passing a list of comments to a `Walker` object.
  * `'threaded'` - `WP_Comment_Query` will fetch the descendant tree for each comment, and return it in a tree structure located in the `children` property of the `WP_Comment` objects.
* `WP_Comment` now has a few utility methods for fetching the descendant tree (`get_children()`), fetching a single direct descendant comment (`get_child()`), and adding anothing `WP_Comment` object as a direct descendant (`add_child()`). Note that `add_child()` only modifies the comment object - it does not touch the database.

Props boonebgorges, wonderboymusic.
See #8071.

git-svn-id: https://develop.svn.wordpress.org/trunk@34546 602fd350-edb4-49c9-b593-d223f7449a82

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

@@ -149,6 +149,15 @@ final class WP_Comment {
 	 */
 	public $user_id = 0;
 
+	/**
+	 * Comment children.
+	 *
+	 * @since 4.4.0
+	 * @access protected
+	 * @var array
+	 */
+	protected $children;
+
 	/**
 	 * Retrieves a WP_Comment instance.
 	 *
@@ -211,4 +220,54 @@ final class WP_Comment {
 	public function to_array() {
 		return get_object_vars( $this );
 	}
+
+	/**
+	 * Get the children of a comment.
+	 *
+	 * @since 4.4.0
+	 * @access public
+	 *
+	 * @return array Array of `WP_Comment` objects.
+	 */
+	public function get_children() {
+		if ( is_null( $this->children ) ) {
+			$this->children = get_comments( array(
+				'parent' => $this->comment_ID,
+				'hierarchical' => 'threaded',
+			) );
+		}
+
+		return $this->children;
+	}
+
+	/**
+	 * Add a child to the comment.
+	 *
+	 * Used by `WP_Comment_Query` when bulk-filling descendants.
+	 *
+	 * @since 4.4.0
+	 * @access public
+	 *
+	 * @param WP_Comment $child Child comment.
+	 */
+	public function add_child( WP_Comment $child ) {
+		$this->comments[ $child->comment_ID ] = $child;
+	}
+
+	/**
+	 * Get a child comment by ID.
+	 *
+	 * @since 4.4.0
+	 * @access public
+	 *
+	 * @param int $child_id ID of the child.
+	 * @return WP_Comment|bool Returns the comment object if found, otherwise false.
+	 */
+	public function get_child( $child_id ) {
+		if ( isset( $this->comments[ $child_id ] ) ) {
+			return $this->comments[ $child_id ];
+		}
+
+		return false;
+	}
 }