Timber\​PostQuery

Query for a collection of WordPress posts.

This is the equivalent of using WP_Query in normal WordPress development.

PostQuery is used directly in Twig templates to iterate through post query results and retrieve meta information about them.

Overview #

This class extends ArrayObject
This class implements Timber\PostCollectionInterface, JsonSerializable
This class uses the traits Timber\AccessesPostsLazily, Timber\CollectsTerms

Properties #

Methods #

Class Methods #

__construct() #

Query for a collection of WordPress posts.

Refer to the official documentation for WP_Query for a list of all the arguments that can be used for the $query parameter.

__construct( \WP_Query $query )

PHP

// Get posts from default query.
global $wp_query;

$posts = Timber::get_posts( $wp_query );

// Using the WP_Query argument format.
$posts = Timber::get_posts( [
    'post_type'     => 'article',
    'category_name' => 'sports',
] );

// Passing a WP_Query instance.
$posts = Timber::get_posts( new WP_Query( [ 'post_type' => 'any' ) );

get_posts() #

DEPRECATED since 2.0.0 use PostCollectionInterface::to_array() instead

Returns: array

pagination() #

Get pagination for a post collection.

Refer to the Pagination Guide for a detailed usage example.

Optionally could be used to get pagination with custom preferences.

pagination( array $prefs = [] )

Returns: \Timber\Pagination object

Twig

{% if posts.pagination.prev %}
    <a href="{{ posts.pagination.prev.link }}">Prev</a>
{% endif %}

<ul class="pages">
    {% for page in posts.pagination.pages %}
        <li>
            <a href="{{ page.link }}" class="{{ page.class }}">{{ page.title }}</a>
        </li>
    {% endfor %}
</ul>

{% if posts.pagination.next %}
    <a href="{{ posts.pagination.next.link }}">Next</a>
{% endif %}

realize() #

Realizes a lazy collection of posts.

For better performance, Post Collections do not instantiate Timber\Post objects at query time. They instantiate each Timber\Post only as needed, i.e. while iterating or for direct array access ($coll[$i]). Since specific Timber\Post implementations may have expensive ::setup() operations, this is usually what you want, but not always. For example, you may want to force eager instantiation to front-load a collection of posts to be cached. To eagerly instantiate a lazy collection of objects is to "realize" that collection.

Returns: self The realized PostQuery.

PHP

$lazy_posts = \Timber\Helper::transient('my_posts', function() {
  return \Timber\Timber::get_posts([
         'post_type' => 'some_post_type',
  ]);
}, HOUR_IN_SECONDS);

foreach ($lazy_posts as $post) {
  // This will incur the performance cost of Post::setup().
}

// Contrast with:

$eager_posts = \Timber\Helper::transient('my_posts', function() {
  $query = \Timber\Timber::get_posts([
         'post_type' => 'some_post_type',
  ]);
  // Incur Post::setup() cost up front.
  return $query->realize();
}, HOUR_IN_SECONDS);

foreach ($eager_posts as $post) {
  // No additional overhead here.
}

terms() #

Get terms from all posts in the collection.

Get terms associated with the posts in this collection, optionally filtered by taxonomy. This is useful for creating taxonomy filters or displaying all terms used across a set of posts.

since 2.4.0

terms( string|array $query_args = [], array $options = [] )

Returns: iterable|array An iterable of Timber\Term objects, or an array of iterables grouped by taxonomy name when merge is false.

PHP

$posts = Timber::get_posts([
    'post_type' => 'projects',
    'category_name' => 'featured',
]);

// Get all terms from all taxonomies
$all_terms = $posts->terms();

// Get terms from a specific taxonomy
$categories = $posts->terms('category');

// Get terms from multiple taxonomies, grouped by taxonomy
$terms_by_tax = $posts->terms(['category', 'post_tag'], ['merge' => false]);

Twig

{# Display filter links for all categories used in the collection #}
{% for category in posts.terms('category') %}
    <a href="{{ category.link }}">{{ category.name }}</a>
{% endfor %}

{# Get terms grouped by taxonomy #}
{% set terms_by_taxonomy = posts.terms('all', {merge: false}) %}
{% for taxonomy, terms in terms_by_taxonomy %}
    <h3>{{ taxonomy }}</h3>
    <ul>
        {% for term in terms %}
            <li>{{ term.name }}</li>
        {% endfor %}
    </ul>
{% endfor %}

to_array() #

Returns: array