Функция get_pages() в WordPress с примерами.

Функция get_pages() в WordPress предоставляет удобный способ получения страниц из базы данных в виде массива объектов. Она была введена в WordPress версии 1.5.0 и с тех пор значительно улучшена. Эта функция кеширует результаты в объектный кэш, что делает её более эффективной при повторных запросах.

get_pages() возвращает массив объектов WP_Post, представляющих страницы, и позволяет извлекать данные по различным критериям. Если тип записи не является иерархическим или указаны некорректные параметры, функция может вернуть false. Для «плоских» типов записей рекомендуется использовать функцию get_posts().

Функция get_pages() также служит основой для функций wp_dropdown_pages() и wp_list_pages() и использует WP_Query с версии WordPress 6.3.

get_pages( array $args = array() )

Параметры

Функция принимает массив параметров, позволяющих настраивать запрос. Рассмотрим основные параметры:

• post_type (string): Определяет тип записи. По умолчанию 'page'. Функция работает только с иерархическими типами записей. Указание post_type = 'post' вернет false.
• post_status (string|array): Статусы страниц для включения в результат. Например: 'publish', 'draft', 'private'. По умолчанию 'publish'.
• exclude (array|string): ID страниц для исключения из результата. Можно указать через запятую или массив.
• exclude_tree (int): ID страницы, для которой нужно исключить всю ветку, включая дочерние страницы.
• include (array|string): ID страниц для включения в результат. Устанавливает hierarchical в false и отменяет параметры child_of, parent, exclude, meta_key, meta_value.
• child_of (int): ID родительской страницы, дочерние страницы которой нужно получить. Возвращает всю иерархию.
• parent (int|array): ID родительской страницы. Возвращает только страницы с указанным родителем, без вложенных страниц.
• hierarchical (bool): Определяет, как выводить страницы. Если true, страницы выводятся в древовидной структуре с отступами. Если false, все страницы выводятся в одном уровне.
• meta_key (string): Выводит страницы, у которых есть указанный ключ метаполя.
• meta_value (string): Выводит страницы, у которых есть указанное значение метаполя. Используется совместно с meta_key.
• authors (string): Выводит страницы, опубликованные указанным автором.
• number (int): Ограничение по количеству страниц, которые нужно вернуть. Работает в связке с offset.
• offset (int): Пропускает указанное количество страниц из начала выборки.
• sort_column (string): Поле для сортировки страниц. Например: 'post_title', 'post_date'.
• sort_order (string): Направление сортировки. Допустимые значения: 'ASC' (по возрастанию) и 'DESC' (по убыванию).
  • 'author' / 'post_author': Сортировка по автору страницы.
  • 'date' / 'post_date': Сортировка по дате публикации страницы.
  • 'title' / 'post_title': Сортировка по заголовку страницы. Это значение по умолчанию и используется для сортировки страниц в алфавитном порядке.
  • 'name' / 'post_name': Сортировка по «slug» страницы, который является её кратким идентификатором.
  • 'modified' / 'post_modified': Сортировка по дате последнего изменения страницы.
  • 'modified_gmt' / 'post_modified_gmt': Сортировка по дате последнего изменения страницы в формате GMT.
  • 'menu_order': Сортировка по порядковому номеру в меню. Полезно для страниц с заданным порядком отображения.
  • 'parent' / 'post_parent': Сортировка по ID родительской страницы. Это может быть полезно для организации иерархии страниц.
  • 'ID': Сортировка по уникальному идентификатору страницы.
  • 'rand': Случайная сортировка страниц, для получения случайного порядка.
  • 'comment_count': Сортировка по количеству комментариев на странице.

Возвращаемое значение

Функция get_pages() возвращает массив объектов WP_Post или false. Массив содержит объекты страниц, соответствующие критериям запроса. Если запрос не возвращает результаты из-за несоответствия типов записи или статусов, функция вернет false.

Шаблон использования

$pages = get_pages([
    'sort_order'   => 'ASC',
    'sort_column'  => 'post_title',
    'hierarchical' => 1,
    'exclude'      => '',
    'include'      => '',
    'meta_key'     => '',
    'meta_value'   => '',
    'authors'      => '',
    'child_of'     => 0,
    'parent'       => -1,
    'exclude_tree' => '',
    'number'       => '',
    'offset'       => 0,
    'post_type'    => 'page',
    'post_status'  => 'publish',
]);

foreach ($pages as $post) {
    setup_postdata($post);
    // формат вывода
}

wp_reset_postdata();

Пример 1: Страницы с указанным шаблоном

Получение страниц, у которых установлен файл шаблона page-wide.php:

$pages = get_pages([
    'meta_key'     => '_wp_page_template',
    'meta_value'   => 'page-wide.php',
    'hierarchical' => 0
]);

foreach ($pages as $page) {
    echo "$page->post_title <br>";
}

Пример 2: Показ дочерних страниц

Вывод динамического списка дочерних страниц, который можно разместить в конце статьи:

<?php
$custom_pages = get_pages([
    'child_of'     => $post->ID,
    'sort_column'  => 'post_date',
    'sort_order'   => 'desc'
]);

foreach ($custom_pages as $page) {
    $content = $page->post_content;

    // Пропускаем страницу без контента
    if (!$content) continue;

    $content = apply_filters('the_content', $content);
    ?>
    <h2><a href="<?php echo get_page_link($page->ID); ?>"><?php echo $page->post_title; ?></a></h2>
    <div class="entry"><?php echo $content; ?></div>
    <?php
}
?>

Пример 3: Показ страниц в выпадающем списке

Создание выпадающего списка со всеми страницами, с использованием функции get_page_link() для получения ссылки на страницу:

<select name="page-dropdown" onchange='document.location.href=this.options[this.selectedIndex].value;'>
    <option value=""><?php echo esc_attr(__('Select page')); ?></option>
    <?php
    $pages = get_pages();
    foreach ($pages as $page) {
        echo '<option value="' . get_page_link($page->ID) . '">' . esc_html($page->post_title) . '</option>';
    }
    ?>
</select>

Пример 4: Показ страниц с использованием фильтра по метаполю

Допустим, вы хотите отобразить страницы, у которых установлен определённый мета:

$pages = get_pages([
    'meta_key'     => 'custom_field_key',
    'meta_value'   => 'custom_value',
    'hierarchical' => false
]);

foreach ($pages as $page) {
    echo '<h2><a href="' . get_page_link($page->ID) . '">' . $page->post_title . '</a></h2>';
}

В этом примере meta_key указывает на произвольное поле, а meta_value — на его значение. Страницы, соответствующие этим критериям, будут выведены в виде ссылок.

Пример 5: Получение страниц с определённым статусом и сортировка по дате

Если вы хотите получить все страницы с статусом 'draft', отсортированные по дате создания в убывающем порядке:

$pages = get_pages([
    'post_status'  => 'draft',
    'sort_column'  => 'post_date',
    'sort_order'   => 'desc'
]);

foreach ($pages as $page) {
    echo '<h2><a href="' . get_page_link($page->ID) . '">' . $page->post_title . '</a></h2>';
}

Пример 6: Вывод страниц с ограничением по числу и пропуском

Если вы хотите получить только 5 страниц, пропуская первые 3:

$pages = get_pages([
    'number'       => 5,
    'offset'       => 3,
    'sort_column'  => 'post_title'
]);

foreach ($pages as $page) {
    echo '<h2><a href="' . get_page_link($page->ID) . '">' . $page->post_title . '</a></h2>';
}

Заключение

Функция get_pages() в WordPress — это инструмент для получения данных о страницах вашего сайта. Она позволяет гибко настраивать выборку страниц в зависимости от ваших потребностей, будь то получение всех страниц, фильтрация по определённым критериям, или отображение страниц в древовидной структуре. С помощью параметров функции можно легко управлять результатами запроса, сортировкой, исключениями и включением определённых страниц.