WordPress.org

Ready to get started?Download WordPress

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Function Reference/get children

Contents

Description

get_children() retrieves attachments, revisions, or sub-pages, possibly by post parent. It works similar to get_posts().

Usage

 <?php $children_array get_children$args$output ); ?> 

Default Usage

<?php $args = array(
	'post_parent' => 0,
	'post_type'   => 'any', 
	'posts_per_page' => -1,
	'post_status' => 'any' ); ?>

Parameters

As of Version 2.6, you must pass a non-empty post_type parameter (either attachment or page).

The following options are available in the $args array:

'numberposts'
(integer) (optional) Number of child posts to retrieve.
Default: '-1'
'post_parent'
(integer) (optional) Pass the ID of a post or Page to get its children. Pass 0 to get attachments without parent. Pass null to get any child regardless of parent.
Default: '0'
'post_type'
(string) (optional) Any value from post_type column of the posts table, such as attachment, page, or revision; or the keyword any.
Default: '0'
'post_status'
(string) (optional) Any value from the post_status column of the wp_posts table, such as publish, draft, or inherit; or the keyword any.
Default: 'any'
'post_mime_type'
(string) (optional) A full or partial mime-type, e.g. image, video, video/mp4, which is matched against a post's post_mime_type field.
Default: None

Note: See get_posts() for a full list of $args parameters.

'output'
(constant) (optional) Variable type of the array items returned by the function: one of OBJECT, ARRAY_A, ARRAY_N.
Default: OBJECT

Return Values

(array) 
Associative array of posts (of variable type set by $output parameter) with post IDs as array keys, or an empty array if no posts are found.

Note: Prior to Version 2.9, the return value would be false when no children found.

Examples

If you just want to get or display attachments, it's probably a little easier to use get_posts() instead.

$images =& get_children( 'post_type=attachment&post_mime_type=image' );

$videos =& get_children( 'post_type=attachment&post_mime_type=video/mp4' );

if ( empty($images) ) {
	// no attachments here
} else {
	foreach ( $images as $attachment_id => $attachment ) {
		echo wp_get_attachment_image( $attachment_id, 'full' );
	}
}

//  If you don't need to handle an empty result:

foreach ( (array) $videos as $attachment_id => $attachment ) {
	echo wp_get_attachment_link( $attachment_id );
}

Show the first image associated with the post

This function retrieves the first image associated with a post

<?php
function echo_first_image( $postID ) {
	$args = array(
		'numberposts' => 1,
		'order' => 'ASC',
		'post_mime_type' => 'image',
		'post_parent' => $postID,
		'post_status' => null,
		'post_type' => 'attachment',
	);

	$attachments = get_children( $args );

	if ( $attachments ) {
		foreach ( $attachments as $attachment ) {
			$image_attributes = wp_get_attachment_image_src( $attachment->ID, 'thumbnail' )  ? wp_get_attachment_image_src( $attachment->ID, 'thumbnail' ) : wp_get_attachment_image_src( $attachment->ID, 'full' );

			echo '<img src="' . wp_get_attachment_thumb_url( $attachment->ID ) . '" class="current">';
		}
	}
}

Show the first image associated with the post and re-key the array

In the example above, a primary array is keyed with the image ID (the exact thing which is being sought - since we don't know it how are we supposed to access it?). The code below provides an easier handle for the image information: the array $child_image. Should be used in the loop.

$args = array(
	'numberposts' => 1,
	'order'=> 'DESC',
	'post_mime_type' => 'image',
	'post_parent' => $post->ID,
	'post_type' => 'attachment'
	);

$get_children_array = get_children($args,ARRAY_A);  //returns Array ( [$image_ID]... 
$rekeyed_array = array_values($get_children_array);
$child_image = $rekeyed_array[0];  


print_r($child_image);  	//Show the contents of the $child_image array.
echo $child_image['ID'];   	//Show the $child_image ID.


Change Log

Since: 2.0.0

Source File

get_children() is located in wp-includes/post.php.

Related

get_children() calls get_posts(), which calls $WP_Query->get_posts().

wp_get_attachment_link(), get_page_children()

See also index of Function Reference and index of Template Tags.