WP_Comment::get_children( array $args = array() ): WP_Comment[]|int[]|int

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$argsarrayoptional

Array of arguments used to pass to get_comments() and determine format. Any other argument accepted by WP_Comment_Query::construct() may also be passed, and is forwarded to get_comments(). Note that parent is always overridden with this comment's ID. A $count or $fields query returns the direct children only, and does not populate the comment's cached children, since that cache holds WP_Comment objects.Default: array()

• $formatstringdefault: 'tree'

  Return value format. 'tree' for a hierarchical tree, 'flat' for a flattened array.

• $statusstringdefault: 'all'

  Comment status to limit results by. Accepts 'hold' (comment_status=0), 'approve' (comment_status=1), 'all', or a custom comment status.

• $hierarchicalstringdefault: 'threaded'

  Whether to include comment descendants in the results. 'threaded' returns a tree, with each comment's children stored in a children property on the WP_Comment object. 'flat' returns a flat array of found comments plus their children. Pass false to leave out descendants. The parameter is ignored (forced to false) when $fields is 'ids' or 'counts'. Accepts 'threaded', 'flat', or false.

• $orderbystring|array

  Comment status or array of statuses. To use 'meta_value' or 'meta_value_num', $meta_key must also be defined. To sort by a specific $meta_query clause, use that clause's array key. Accepts 'comment_agent', 'comment_approved', 'comment_author', 'comment_author_email', 'comment_author_IP', 'comment_author_url', 'comment_content', 'comment_date', 'comment_date_gmt', 'comment_ID', 'comment_karma', 'comment_parent', 'comment_post_ID', 'comment_type', 'user_id', 'comment__in', 'meta_value', 'meta_value_num', the value of $meta_key, and the array keys of $meta_query. Also accepts false, an empty array, or 'none' to disable ORDER BY clause.

• $fieldsstringdefault: empty

  Which fields to return. Accepts 'ids' for comment IDs, or an empty string for full WP_Comment objects.

• $countbooldefault: false

  Whether to return a comment count rather than comments.

• $typestringdefault: empty

  Limit results to comments of a given type, such as 'comment', 'pingback', 'trackback', or 'note'. Accepts 'all' for every type.

• $numberintdefault: empty (no limit)

  Maximum number of comments to retrieve.

• $post_idintdefault: 0

  Limit results to comments on a given post.

• $orderstringdefault: 'DESC'

  How to order retrieved comments. Accepts 'ASC' or 'DESC'.

Return value

WP_Comment[]|int[]|int

Array of WP_Comment objects, an array of comment IDs when $fields is 'ids', or the number of children when $count is true.

Performance profile

How much work a call to WP_Comment::get_children() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Heavy

Reaches the database via get_comments().

Scaling

Scales with input

The body loops, so the work grows with what you pass in.

Instructions

16–40

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 70.

Plugin surface

None

Nothing here hands control to plugin code.

Called by

0

Nothing in core calls this; the cost is only what you spend yourself.

What it touches

• querycontent queryget_comments()called directly

Further down the call graph this can also reach hook. That is the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 2 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost WP_Comment::get_children() can have, taken from its control-flow graph on PHP 8.5.

Uses · 2

• wp_parse_args()Merges user defined arguments into defaults array.
• get_comments()Retrieves a list of comments.

Source code

View on Trac ↗View on GitHub ↗

385	public function get_children( $args = array() ) {386		$defaults = array(387			'format'       => 'tree',388			'status'       => 'all',389			'hierarchical' => 'threaded',390			'orderby'      => '',391		);392 393		/** @var array{ format: 'tree'|'flat', status: string, hierarchical: 'threaded'|'flat'|false, orderby: string|string[]|false, fields?: 'ids'|'', count?: bool, type?: string, number?: int, post_id?: int, order?: 'ASC'|'DESC', ... } $_args */394		$_args           = wp_parse_args( $args, $defaults );395		$_args['parent'] = $this->comment_ID;396 397		/*398		 * A 'count' or 'ids' query returns an integer or a list of comment IDs rather than399		 * WP_Comment objects. Neither may be written to the children cache, which holds400		 * WP_Comment objects and is read back by add_child(), get_child(), and the 'flat'401		 * format below. Return the result directly and leave the cache untouched. The two402		 * branches must stay separate: each is narrowed independently, and `count` is only403		 * safe to overwrite in the 'ids' branch.404		 */405		if ( ! empty( $_args['count'] ) ) {406			return get_comments( $_args );407		} elseif ( isset( $_args['fields'] ) && 'ids' === $_args['fields'] ) {408			$_args['count'] = false; // For static analysis of the conditional return type.409			return get_comments( $_args );410		}411 412		// Only WP_Comment objects are returned past this point. Stated positively for static analysis.413		$_args['count']  = false;414		$_args['fields'] = '';415 416		if ( is_null( $this->children ) ) {417			if ( $this->populated_children ) {418				$this->children = array();419			} else {420				$this->children = get_comments( $_args );421			}422		}423 424		if ( 'flat' === $_args['format'] ) {425			$children = array();426			foreach ( $this->children as $child ) {427				$child_args           = $_args;428				$child_args['format'] = 'flat';429				// get_children() resets this value automatically.430				unset( $child_args['parent'] );431 432				$children = array_merge( $children, array( $child ), $child->get_children( $child_args ) );433			}434		} else {435			$children = $this->children;436		}437 438		return $children;439	}

Changelog

Introduced in 4.4.0. One change between 6.7.7 and 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 7.1.0 tag, from src/wp-includes/class-wp-comment.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.