get_pages()

You are here:

get_pages( array|string $args = array() )

Retrieve a list of pages (or hierarchical post type items).

Parameters Parameters

$args

(array|string) (Optional) Array or string of arguments to retrieve pages.

  • ‘child_of’
    (int) Page ID to return child and grandchild pages of. Note: The value of $hierarchical has no bearing on whether $child_of returns hierarchical results. Default 0, or no restriction.
  • ‘sort_order’
    (string) How to sort retrieved pages. Accepts ‘ASC’, ‘DESC’. Default ‘ASC’.
  • ‘sort_column’
    (string) What columns to sort pages by, comma-separated. Accepts ‘post_author’, ‘post_date’, ‘post_title’, ‘post_name’, ‘post_modified’, ‘menu_order’, ‘post_modified_gmt’, ‘post_parent’, ‘ID’, ‘rand’, ‘comment*count’. ‘post*’ can be omitted for any values that start with it. Default ‘post_title’.
  • ‘hierarchical’
    (bool) Whether to return pages hierarchically. If false in conjunction with $child_of also being false, both arguments will be disregarded. Default true.
  • ‘exclude’
    (array) Array of page IDs to exclude.
  • ‘include’
    (array) Array of page IDs to include. Cannot be used with $child_of$parent$exclude$meta_key$meta_value, or $hierarchical.
  • ‘meta_key’
    (string) Only include pages with this meta key.
  • ‘meta_value’
    (string) Only include pages with this meta value. Requires $meta_key.
  • ‘authors’
    (string) A comma-separated list of author IDs.
  • ‘parent’
    (int) Page ID to return direct children of. Default -1, or no restriction.
  • ‘exclude_tree’
    (string|array) Comma-separated string or array of page IDs to exclude.
  • ‘number’
    (int) The number of pages to return. Default 0, or all pages.
  • ‘offset’
    (int) The number of pages to skip before returning. Requires $number. Default 0.
  • ‘post_type’
    (string) The post type to query. Default ‘page’.
  • ‘post_status’
    (string|array) A comma-separated list or array of post statuses to include. Default ‘publish’.

 

Default value: array()


Top ↑

Return Return

(array|false) List of pages matching defaults or $args.


Top ↑

Source Source

File: wp-includes/post.php

5391
5392
5393
5394
5395
5396
5397
5398
5399
5400
5401
5402
5403
5404
5405
5406
5407
5408
5409
5410
5411
5412
5413
5414
5415
5416
5417
5418
5419
5420
5421
5422
5423
5424
5425
5426
5427
5428
5429
5430
5431
5432
5433
5434
5435
5436
5437
5438
5439
5440
5441
5442
5443
5444
5445
5446
5447
5448
5449
5450
5451
5452
5453
5454
5455
5456
5457
5458
5459
5460
5461
5462
5463
5464
5465
5466
5467
5468
5469
5470
5471
5472
5473
5474
5475
5476
5477
5478
5479
5480
5481
5482
5483
5484
5485
5486
5487
5488
5489
5490
5491
5492
5493
5494
5495
5496
5497
5498
5499
5500
5501
5502
5503
5504
5505
5506
5507
5508
5509
5510
5511
5512
5513
5514
5515
5516
5517
5518
5519
5520
5521
5522
5523
5524
5525
5526
5527
5528
5529
5530
5531
5532
5533
5534
5535
5536
5537
5538
5539
5540
5541
5542
5543
5544
5545
5546
5547
5548
5549
5550
5551
5552
5553
5554
5555
5556
5557
5558
5559
5560
5561
5562
5563
5564
5565
5566
5567
5568
5569
5570
5571
5572
5573
5574
5575
5576
5577
5578
5579
5580
5581
5582
5583
5584
5585
5586
5587
5588
5589
5590
5591
5592
5593
5594
5595
5596
5597
5598
5599
5600
5601
5602
5603
5604
5605
5606
5607
5608
5609
5610
5611
5612
5613
5614
5615
5616
5617
5618
5619
5620
5621
5622
5623
5624
5625
5626
5627
5628
5629
5630
5631
5632
5633
5634
5635
5636
5637
5638
5639
5640
5641
5642
5643
5644
5645
5646
5647
5648
5649
5650
5651
5652
5653
5654
5655
5656
5657
5658
5659
5660
5661
5662
5663
5664
5665
function get_pages( $args = array() ) {
    global $wpdb;
 
    $defaults = array(
        'child_of'     => 0,
        'sort_order'   => 'ASC',
        'sort_column'  => 'post_title',
        'hierarchical' => 1,
        'exclude'      => array(),
        'include'      => array(),
        'meta_key'     => '',
        'meta_value'   => '',
        'authors'      => '',
        'parent'       => -1,
        'exclude_tree' => array(),
        'number'       => '',
        'offset'       => 0,
        'post_type'    => 'page',
        'post_status'  => 'publish',
    );
 
    $parsed_args = wp_parse_args( $args, $defaults );
 
    $number       = (int) $parsed_args['number'];
    $offset       = (int) $parsed_args['offset'];
    $child_of     = (int) $parsed_args['child_of'];
    $hierarchical = $parsed_args['hierarchical'];
    $exclude      = $parsed_args['exclude'];
    $meta_key     = $parsed_args['meta_key'];
    $meta_value   = $parsed_args['meta_value'];
    $parent       = $parsed_args['parent'];
    $post_status  = $parsed_args['post_status'];
 
    // Make sure the post type is hierarchical.
    $hierarchical_post_types = get_post_types( array( 'hierarchical' => true ) );
    if ( ! in_array( $parsed_args['post_type'], $hierarchical_post_types, true ) ) {
        return false;
    }
 
    if ( $parent > 0 && ! $child_of ) {
        $hierarchical = false;
    }
 
    // Make sure we have a valid post status.
    if ( ! is_array( $post_status ) ) {
        $post_status = explode( ',', $post_status );
    }
    if ( array_diff( $post_status, get_post_stati() ) ) {
        return false;
    }
 
    // $args can be whatever, only use the args defined in defaults to compute the key.
    $key          = md5( serialize( wp_array_slice_assoc( $parsed_args, array_keys( $defaults ) ) ) );
    $last_changed = wp_cache_get_last_changed( 'posts' );
 
    $cache_key = "get_pages:$key:$last_changed";
    $cache     = wp_cache_get( $cache_key, 'posts' );
    if ( false !== $cache ) {
        // Convert to WP_Post instances.
        $pages = array_map( 'get_post', $cache );
        /** This filter is documented in wp-includes/post.php */
        $pages = apply_filters( 'get_pages', $pages, $parsed_args );
        return $pages;
    }
 
    $inclusions = '';
    if ( ! empty( $parsed_args['include'] ) ) {
        $child_of     = 0; // Ignore child_of, parent, exclude, meta_key, and meta_value params if using include.
        $parent       = -1;
        $exclude      = '';
        $meta_key     = '';
        $meta_value   = '';
        $hierarchical = false;
        $incpages     = wp_parse_id_list( $parsed_args['include'] );
        if ( ! empty( $incpages ) ) {
            $inclusions = ' AND ID IN (' . implode( ',', $incpages ) . ')';
        }
    }
 
    $exclusions = '';
    if ( ! empty( $exclude ) ) {
        $expages = wp_parse_id_list( $exclude );
        if ( ! empty( $expages ) ) {
            $exclusions = ' AND ID NOT IN (' . implode( ',', $expages ) . ')';
        }
    }
 
    $author_query = '';
    if ( ! empty( $parsed_args['authors'] ) ) {
        $post_authors = wp_parse_list( $parsed_args['authors'] );
 
        if ( ! empty( $post_authors ) ) {
            foreach ( $post_authors as $post_author ) {
                // Do we have an author id or an author login?
                if ( 0 == intval( $post_author ) ) {
                    $post_author = get_user_by( 'login', $post_author );
                    if ( empty( $post_author ) ) {
                        continue;
                    }
                    if ( empty( $post_author->ID ) ) {
                        continue;
                    }
                    $post_author = $post_author->ID;
                }
 
                if ( '' === $author_query ) {
                    $author_query = $wpdb->prepare( ' post_author = %d ', $post_author );
                } else {
                    $author_query .= $wpdb->prepare( ' OR post_author = %d ', $post_author );
                }
            }
            if ( '' !== $author_query ) {
                $author_query = " AND ($author_query)";
            }
        }
    }
 
    $join  = '';
    $where = "$exclusions $inclusions ";
    if ( '' !== $meta_key || '' !== $meta_value ) {
        $join = " LEFT JOIN $wpdb->postmeta ON ( $wpdb->posts.ID = $wpdb->postmeta.post_id )";
 
        // meta_key and meta_value might be slashed.
        $meta_key   = wp_unslash( $meta_key );
        $meta_value = wp_unslash( $meta_value );
        if ( '' !== $meta_key ) {
            $where .= $wpdb->prepare( " AND $wpdb->postmeta.meta_key = %s", $meta_key );
        }
        if ( '' !== $meta_value ) {
            $where .= $wpdb->prepare( " AND $wpdb->postmeta.meta_value = %s", $meta_value );
        }
    }
 
    if ( is_array( $parent ) ) {
        $post_parent__in = implode( ',', array_map( 'absint', (array) $parent ) );
        if ( ! empty( $post_parent__in ) ) {
            $where .= " AND post_parent IN ($post_parent__in)";
        }
    } elseif ( $parent >= 0 ) {
        $where .= $wpdb->prepare( ' AND post_parent = %d ', $parent );
    }
 
    if ( 1 === count( $post_status ) ) {
        $where_post_type = $wpdb->prepare( 'post_type = %s AND post_status = %s', $parsed_args['post_type'], reset( $post_status ) );
    } else {
        $post_status     = implode( "', '", $post_status );
        $where_post_type = $wpdb->prepare( "post_type = %s AND post_status IN ('$post_status')", $parsed_args['post_type'] );
    }
 
    $orderby_array = array();
    $allowed_keys  = array(
        'author',
        'post_author',
        'date',
        'post_date',
        'title',
        'post_title',
        'name',
        'post_name',
        'modified',
        'post_modified',
        'modified_gmt',
        'post_modified_gmt',
        'menu_order',
        'parent',
        'post_parent',
        'ID',
        'rand',
        'comment_count',
    );
 
    foreach ( explode( ',', $parsed_args['sort_column'] ) as $orderby ) {
        $orderby = trim( $orderby );
        if ( ! in_array( $orderby, $allowed_keys, true ) ) {
            continue;
        }
 
        switch ( $orderby ) {
            case 'menu_order':
                break;
            case 'ID':
                $orderby = "$wpdb->posts.ID";
                break;
            case 'rand':
                $orderby = 'RAND()';
                break;
            case 'comment_count':
                $orderby = "$wpdb->posts.comment_count";
                break;
            default:
                if ( 0 === strpos( $orderby, 'post_' ) ) {
                    $orderby = "$wpdb->posts." . $orderby;
                } else {
                    $orderby = "$wpdb->posts.post_" . $orderby;
                }
        }
 
        $orderby_array[] = $orderby;
 
    }
    $sort_column = ! empty( $orderby_array ) ? implode( ',', $orderby_array ) : "$wpdb->posts.post_title";
 
    $sort_order = strtoupper( $parsed_args['sort_order'] );
    if ( '' !== $sort_order && ! in_array( $sort_order, array( 'ASC', 'DESC' ), true ) ) {
        $sort_order = 'ASC';
    }
 
    $query  = "SELECT * FROM $wpdb->posts $join WHERE ($where_post_type) $where ";
    $query .= $author_query;
    $query .= ' ORDER BY ' . $sort_column . ' ' . $sort_order;
 
    if ( ! empty( $number ) ) {
        $query .= ' LIMIT ' . $offset . ',' . $number;
    }
 
    $pages = $wpdb->get_results( $query );
 
    if ( empty( $pages ) ) {
        wp_cache_set( $cache_key, array(), 'posts' );
 
        /** This filter is documented in wp-includes/post.php */
        $pages = apply_filters( 'get_pages', array(), $parsed_args );
        return $pages;
    }
 
    // Sanitize before caching so it'll only get done once.
    $num_pages = count( $pages );
    for ( $i = 0; $i < $num_pages; $i++ ) {
        $pages[ $i ] = sanitize_post( $pages[ $i ], 'raw' );
    }
 
    // Update cache.
    update_post_cache( $pages );
 
    if ( $child_of || $hierarchical ) {
        $pages = get_page_children( $child_of, $pages );
    }
 
    if ( ! empty( $parsed_args['exclude_tree'] ) ) {
        $exclude = wp_parse_id_list( $parsed_args['exclude_tree'] );
        foreach ( $exclude as $id ) {
            $children = get_page_children( $id, $pages );
            foreach ( $children as $child ) {
                $exclude[] = $child->ID;
            }
        }
 
        $num_pages = count( $pages );
        for ( $i = 0; $i < $num_pages; $i++ ) {
            if ( in_array( $pages[ $i ]->ID, $exclude, true ) ) {
                unset( $pages[ $i ] );
            }
        }
    }
 
    $page_structure = array();
    foreach ( $pages as $page ) {
        $page_structure[] = $page->ID;
    }
 
    wp_cache_set( $cache_key, $page_structure, 'posts' );
 
    // Convert to WP_Post instances.
    $pages = array_map( 'get_post', $pages );
 
    /**
     * Filters the retrieved list of pages.
     *
     * @since 2.1.0
     *
     * @param WP_Post[] $pages       Array of page objects.
     * @param array     $parsed_args Array of get_pages() arguments.
     */
    return apply_filters( 'get_pages', $pages, $parsed_args );
}


Top ↑

Changelog Changelog

Changelog
VersionDescription
1.5.0Introduced.
Was this article helpful?
Dislike 0
Views: 2

Cart

Log in

Create an Account
Back to Top