Timber\​PostArrayObject

Overview #

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

Methods #

Class Methods #

__construct() #

Takes an arbitrary array of WP_Posts to wrap and (lazily) translate to Timber\Post instances.

__construct( array $posts )

get_posts() #

DEPRECATED since 2.0.0 use PostCollectionInterface::to_array() instead

Returns: array

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