Timber Documentation

To improve performance when working with Timber posts, follow these best practices:

1. Use pre_get_posts: If you need to modify the query before WordPress determines the template, use the standard WordPress pre_get_posts action instead of passing arguments to Timber::get_posts() or Timber::get_post(), which always trigger a database hit.
2. Disable row counting: When querying a collection where pagination is not required, set 'no_found_rows' => true in your query arguments to avoid the overhead of counting total matching rows.
3. Eagerly realize collections for caching: Timber collections are lazy-loaded (containing raw WP_Post objects until accessed). If you are caching a collection via a transient, call $query->realize() to convert all raw posts into Timber\Post objects immediately. This ensures that when the cached data is retrieved later, the expensive instantiation work is already done.

// Disable row counting for better performance
$posts = Timber::get_posts([
    'no_found_rows' => true,
]);

// Eagerly realize a collection before caching it in a transient
$eager_posts = \Timber\Helper::transient('my_posts', function () {
    $query = \Timber\Timber::get_posts([
        'post_type' => 'some_post_type',
    ]);

    // Run Post::setup() up front.
    return $query->realize();
}, HOUR_IN_SECONDS);

In Timber 2.0, Timber\PostPreview has been renamed to Timber\PostExcerpt to align with WordPress terminology.

• Use Timber\Post::excerpt() instead of Timber\Post::preview().
• The post.excerpt Twig function now accepts arguments via array/hash notation.

PHP Usage:

$post->excerpt([
    'words' => 50,
    'chars' => false,
    'end' => '…',
    'force' => false,
    'strip' => true,
    'read_more' => 'Read More',
]);

Twig Usage:

{{ post.excerpt({
    words: 50,
    chars: false,
    end: "…",
    force: false,
    strip: true,
    read_more: "Read More"
}) }}

New Excerpt Parameters:

• always_add_read_more: Controls whether a read more link is added even if the excerpt isn't trimmed. (Default: false)
• always_add_end: Controls whether the end string is added even if the excerpt isn't trimmed. (Default: false)

Global Defaults: You can filter the default excerpt options using the timber/post/excerpt/defaults filter:

add_filter('timber/post/excerpt/defaults', function ($defaults) {
    $defaults['always_add_read_more'] = false;
    $defaults['words'] = 240;
    return $defaults;
});

To display products in a loop (e.g., views/partials/tease-product.twig), you must call the timber_set_product helper function to ensure each product in the loop has the correct WooCommerce context. Without this, products may incorrectly display data from the first item in the loop.

1. Add the helper to functions.php:

<?php
function timber_set_product( $post ) {
    global $product;

    if ( is_woocommerce() ) {
        $product = wc_get_product( $post->ID );
    }
}

2. Call the helper in your Twig template:

{{ fn('timber_set_product', post) }}

<article {{ fn('post_class', ['$classes', 'entry'] ) }}>

    {{ fn('timber_set_product', post) }}

    <div class="media">

        {% if showthumb %}
            <div class="media-figure {% if not post.thumbnail %}placeholder{% endif %}">
                <a href="{{ post.link }}">
                    {% if post.thumbnail %}
                        <img src="{{ post.thumbnail.src|resize(post_thumb_size[0], post_thumb_size[1]) }}" />
                    {% else %}
                        <span class="thumb-placeholder"><i class="icon-camera"></i></span>
                    {% endif %}
                </a>
            </div>
        {% endif %}

        <div class="media-content">

            {% do action('woocommerce_before_shop_loop_item_title') %}

            {% if post.title %}
                <h3 class="entry-title"><a href="{{ post.link }}">{{ post.title }}</a></h3>
            {% else %}
                <h3 class="entry-title"><a href="{{ post.link }}">{{ fn('the_title') }}</a></h3>
            {% endif %}

            {% do action( 'woocommerce_after_shop_loop_item_title' ) %}
            {% do action( 'woocommerce_after_shop_loop_item' ) %}

        </div>

    </div>

</article>