get_children( mixed $args = '', string $output = OBJECT ): WP_Post[]|array[]|int[]
- Since
- 2.0.0
- Source
wp-includes/post.php:970
Description
Normally, without any enhancements, the children would apply to pages. In the context of the inner workings of WordPress, pages, posts, and attachments share the same table, so therefore the functionality could apply to any one of them. It is then noted that while this function does not work on posts, it does not mean that it won't work on posts. It is recommended that you know what context you wish to retrieve the children of.
Attachments may also be made the child of a post, so if that is an accurate statement (which needs to be verified), it would then be possible to get all of the attachments for a post. Attachments have since changed since version 2.5, so this is most likely inaccurate, but serves generally as an example of what is possible.
The arguments listed as defaults are for this function and also of the get_posts() function. The arguments are combined with the get_children defaults and are then passed to the get_posts() function, which accepts additional arguments.
You can replace the defaults in this function, listed below and the additional arguments listed in the get_posts() function.
The 'post_parent' is the most important argument and important attention needs to be paid to the $args parameter. If you pass either an object or an integer (number), then just the 'post_parent' is grabbed and everything else is lost. If you don't specify any arguments, then it is assumed that you are in The Loop and the post parent will be grabbed for from the current post.
The 'post_parent' argument is the ID to get the children. The 'numberposts' is the amount of posts to retrieve that has a default of '-1', which is used to get all of the posts. Giving a number higher than 0 will only retrieve that amount of posts.
The 'post_type' and 'post_status' arguments can be used to choose what criteria of posts to retrieve. The 'post_type' can be anything, but WordPress post types are 'post', 'pages', and 'attachments'. The 'post_status' argument will accept any post status within the write administration panels.
Compatibility
- WordPress
- since 2.0.0
- PHP
- 7.4–8.6-dev
- 6.7.7
- 6.8.8
- 6.9.7
- 7.0.4
- 7.1.0
Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.
Parameters
$argsmixedoptional- User defined arguments for replacing the defaults. Default empty.Default:
'' $outputstringoptional- The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to a WP_Post object, an associative array, or a numeric array, respectively. Default OBJECT.Default:
OBJECT
Return value
WP_Post[]|array[]|int[]- Array of post objects, arrays, or IDs, depending on
$output.
Performance profile
How much work a call to 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
- Scaling
- Scales with input
- Instructions
- 8–47
- Plugin surface
- None
- Called by
- 7
Reaches the database via get_posts().
The body loops, so the work grows with what you pass in.
Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 97.
Nothing here hands control to plugin code.
7 places in core call this, so the cost is paid more often than your own code shows.
What it touches
- querycontent query
get_posts()called directly - cacheobject cache
wp_cache_add_multiple()one call below get_children()
Further down the call graph this can also reach hook, option, serialize and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.
What one call costs · 3 distinct outcomes
One number would be a lie: the work depends on which branch runs. These are every distinct cost get_children() can have, taken from its control-flow graph on PHP 8.5.
| When | Instructions | Calls it makes |
|---|---|---|
empty($args) && !isset($value) | 8 | none |
| always | 21–27 | wp_parse_args(), get_posts() |
empty($parsed_args) | 31–47 | wp_parse_args(), get_posts(), update_post_cache() |
Across PHP versions
| PHP | Compiled | Executed | Branches | Notes |
|---|---|---|---|---|
| 8.6-dev | 97 | 8–47 | 15 | |
| 8.5 | 97 | 8–47 | 15 | |
| 8.4 | 97 | 8–47 | 15 | 2 fewer instructions than PHP 8.3 |
| 8.3 | 99 | 8–48 | 15 | |
| 8.2 | 99 | 8–48 | 15 | |
| 8.1 | 99 | 8–48 | 15 | 2 fewer instructions than PHP 7.4 |
| 7.4 | 101 | 9–49 | 15 |
An instruction is not a fixed amount of time, so a matching count is not necessarily the same speed; what it rules out is a difference in the work itself.
Uses · 3
- wp_parse_args()Merges user defined arguments into defaults array.
- get_posts()Retrieves an array of the latest posts, or posts matching the given criteria.
- update_post_cache()Updates posts in cache.
Used by · 7
- _wp_after_delete_font_family()Deletes child font faces when a font family is deleted.
- gallery_shortcode()Builds the Gallery shortcode output.
- get_adjacent_image_link()Gets the next or previous image link that has the same post parent.
- get_attached_media()Retrieves media attached to the passed post.
- get_media_items()Retrieves HTML for media items of post gallery.
- wp_get_post_revisions()Returns all revisions of specified post.
- wp_playlist_shortcode()Builds the Playlist shortcode output.
Source code
function get_children( $args = '', $output = OBJECT ) { $kids = array(); if ( empty( $args ) ) { if ( isset( $GLOBALS['post'] ) ) { $args = array( 'post_parent' => (int) $GLOBALS['post']->post_parent ); } else { return $kids; } } elseif ( is_object( $args ) ) { $args = array( 'post_parent' => (int) $args->post_parent ); } elseif ( is_numeric( $args ) ) { $args = array( 'post_parent' => (int) $args ); } $defaults = array( 'numberposts' => -1, 'post_type' => 'any', 'post_status' => 'any', 'post_parent' => 0, ); $parsed_args = wp_parse_args( $args, $defaults ); $children = get_posts( $parsed_args ); if ( ! $children ) { return $kids; } if ( ! empty( $parsed_args['fields'] ) ) { return $children; } update_post_cache( $children ); foreach ( $children as $key => $child ) { $kids[ $child->ID ] = $children[ $key ]; } if ( OBJECT === $output ) { return $kids; } elseif ( ARRAY_A === $output ) { $weeuns = array(); foreach ( (array) $kids as $kid ) { $weeuns[ $kid->ID ] = get_object_vars( $kids[ $kid->ID ] ); } return $weeuns; } elseif ( ARRAY_N === $output ) { $babes = array(); foreach ( (array) $kids as $kid ) { $babes[ $kid->ID ] = array_values( get_object_vars( $kids[ $kid->ID ] ) ); } return $babes; } else { return $kids; }}Changelog
Introduced in 2.0.0. Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
About this page
- Parsed data
- Generated from the wordpress-develop 6.8.8 tag, from
src/wp-includes/post.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.