Upgrade to 2.0

Version 2.0 of Timber

Will only work as a Composer package.
Tries to make the naming of functions and filters more consistent.
Refactors how Timber Core works under the hood to improve compatibility with WordPress Core and be ready for future challenges.
Removes a lot of deprecated code.

New requirements #

We upgraded Timber to work with more modern PHP and functionalities that only were introduced in newer versions of Timber. That’s why we now have the following requirements to run Timber:

Timber 2.0 requires you to use a PHP version >= 7.4.
Timber 2.0 requires WordPress 5.3 or greater. This was changed to take advantage of new Date/Time improvements built into WordPress. If you need to use WordPress 5.2 or earlier, please continue to use Timber 1.x.
Timber now requires Twig in a version >= 2.15.3.

No more plugin support #

As of version 2.0, We will stop releasing Timber as a plugin. You need to install it through Composer.

If you are currently using Timber as a plugin, you can follow this guide to switch from the plugin to Timber 1.x. After that, you can follow the Upgrade to 2.0 guide to switch from (Composer-based) Timber 1.x to Timber 2.0.

Initializing Timber #

Up until now, you had to initialize Timber by instantiating a new object of the Timber\Timber class. The constructor of that class is now protected and you’ll run into an error (Call to protected Timber\Timber::__construct() from invalid context) if you try to initialize Timber with it.

🚫 Before

new Timber\Timber();

The new way to initialize Timber is to call Timber\Timber::init().

✅ Now

Timber\Timber::init();

Don’t use a `$timber` global #

The Timber\Timber::init() method doesn’t return anything. If you use an older pattern where you use a global variable to assign Timber, then it won’t do anything:

🚫 Don’t do this

global $timber;

$timber = Timber\Timber::init();

Checking Timber’s version #

If you need to check what Timber version is installed, you can use Timber::version.

if (version_compare(Timber::$version, '2.0.0', '>=')) {
    // Timber 2.x is installed.
}

Removed functionality #

Removed Routes #

The routing feature had been deprecated in Timber 1.x and was fully removed in Timber 2.0. Routing in Timber is outside its primary mission. Many of its use cases can usually be solved via existing WordPress functionality. We wanted to make it easier for developers to use other routing libraries.

In case you still need routing as it were before, you can install the library that Timber used before:

composer require upstatement/routes

Or you can use one of the available libraries and hook it into your code. Follow the Routing Guide for more information.

Removed Twig cache extension #

Timber used the twig/cache-extension package, which was abandoned. You only need this package if you’ve used the {% cache %} tag in Twig.

You should use twig/cache-extra instead, which you can implement yourself. Check you the relevant section in the Performance/Caching Guide for more information.

If you still need the twig/cache-extension package before moving to twig/cache-extra, you can still install it yourself:

composer require twig/cache-extension

And then, you can enable it with the following filter:

functions.php

add_filter('timber/cache/enable_extension', '__return_true');

Removed `Timber\Request` class #

We removed the Timber\Request class without replacement, because it provided only limited functionality.

The Timber\Request class was used to create a request entry in the global Timber context. With this you had access to $_GET and $_POST in Twig.

🚫 This doesn’t work anymore

{{ request.get }}

{% if request.get.something %}{% endif %}

{{ request.post }}

{% if request.post.something %}{% endif %}

If you still need to work with requests in Twig, you can use a maintained and well-tested library. Here are some examples:

Nyholm/psr7 – A super lightweight PSR-7 implementation.
guzzle/psr7 – PSR-7 HTTP message library.
laminas/laminas-diactoros – PSR HTTP Message implementations

And here’s an example for how you could add Nyholm/psr7 as a request object in Twig.

add_filter('timber/context', function($context) {
    $psr17Factory = new \Nyholm\Psr7\Factory\Psr17Factory();

    $creator = new \Nyholm\Psr7Server\ServerRequestCreator(
        $psr17Factory, // ServerRequestFactory
        $psr17Factory, // UriFactory
        $psr17Factory, // UploadedFileFactory
        $psr17Factory  // StreamFactory
    );

    $context['request'] = $creator->fromGlobals();

    return $context;
});

Namespaced class names #

Namespaced class names were already introduced in Timber version 1.0. Up until now, you could still the use the old, non-namespaced class names. Only namespaced class names are used now. In version 2.0, we removed the following class aliases:

TimberArchives, use Timber\Archives instead
TimberComment, use Timber\Comment instead
TimberCore, use Timber\Core instead
TimberFunctionWrapper, use Timber\FunctionWrapper instead
TimberHelper, use Timber\Helper instead
TimberImage, use Timber\Image instead
TimberImageHelper, use Timber\ImageHelper instead
TimberIntegrations, use Timber\Integrations instead
TimberLoader, use Timber\Loader instead
TimberMenu, use Timber\Menu instead
TimberMenuItem, use Timber\MenuItem instead
TimberPost, use Timber\Post instead
TimberPostCollection, without replacement
Timber\PostsCollection, without replacement
TimberPostGetter, without replacement
TimberQueryIterator, without replacement
TimberRequest, without replacement
TimberSite, use Timber\Site instead
TimberTerm, use Timber\Term instead
TimberTermGetter, without replacement
TimberTheme, use Timber\Theme instead
TimberTwig, use Timber\Twig instead
TimberURLHelper, use Timber\URLHelper instead
TimberUser, use Timber\User instead
TimberCommand, use Timber\Command instead
Timber_WP_CLI_Command, use Timber\Timber_WP_CLI_Command instead

Timber\Timber #

A special case is the class alias Timber for the Timber\Timber class. We decided to keep it, because it’s more convenient to write Timber::render() instead of Timber\Timber::render() if you don’t use the use operator.

Twig classes #

Timber requires a Twig version (2.12) which comes with its own namespaced classes:

Instead of Twig_Function or Twig_SimpleFunction, you need to use Twig\TwigFunction.
Instead of Twig_Filter or Twig_SimpleFilter, you need to use Twig\TwigFilter.
Instead of Twig_Environment, you need to use Twig\Environment.

You maybe use one of those classes with the timber/twig filter. Make sure you update them.

In Timber v1, we used to have Timber\Twig_Function and Timber\Twig_Filter as interim classes that could be used for better compatibility with the different class names that exist with Twig. These are now removed as well. Use the classes Twig\TwigFunction and Twig\TwigFilter instead.

An updated API to get Timber objects #

In Timber 2.0, we updated the API to get Timber objects to avoid certain pitfalls. Here’s the short list:

Use Timber::get_post() to get a post. Using new Timber\Post() will not work anymore.
Use Timber::get_posts() to get posts. Using new Timber\PostQuery() will not work anymore.
Use Timber::get_term() to get a term. Using new Timber\Term() will not work anymore.
Use Timber::get_terms() to get terms.
Use Timber::get_comment() to get a comment. Using new Timber\Comment() will not work anymore.
Use Timber::get_comments() to get comments.
Use Timber::get_menu() to get a menu. Using new Timber\Menu() will not work anymore.
Use Timber::get_user() to get a user. Using new Timber\User() will not work anymore.
Use Timber::get_users() to get users.

You will find more details in the following sections.

Factories #

Behind the scenes, Timber now uses a Factory Pattern to get Timber objects. We added factories for posts, terms, menus, menu items, comments and users. Most of the work for version 2 went into the factories.

No worries, you don’t have to understand this programming pattern to work with Timber. But it is very helpful for developers who use advanced coding patterns and extend Timber with their own PHP classes. Now it’s easier to control which PHP classes are used to create the different Timber objects using Class Maps.

Removed classes #

By using the Factory Pattern, we refactored a lot of code and by moving logic into the factory classes were able to remove the following classes:

Timber\PostCollection – Timber now uses different classes for collections of posts, that all implement the new Timber\PostCollectionInterface. Learn more about Post Collections in the Posts Guide.
Timber\PostGetter
Timber\TermGetter
Timber\QueryIterator

Better compatibility with plugins #

We updated the Timber\PostsIterator class for better compatibility with other WordPress plugins when looping over posts. We took great care to make sure that Timber calls the right functions and WordPress hooks in the right places when looping over posts.

For this, we used setup() and teardown() methods for posts. These methods can be used if you need to manipulate post objects before they are accessed in a loop.

We removed the timber/class/posts_iterator filter hook, which you could use to use a custom post iterator. The functionality that you handled with a custom post iterator can now be handled with the setup() and teardown() methods on a post. To write custom setup() and teardown() methods, you can extend the Timber\Post class. Learn more about extending Timber in the Extending Timber Guide.

If you’ve used a custom post iterator to handle a plugin incompatibility before, it might be that you won’t need to do anything and that the issue is resolved with the existing post iterator implementation in Timber 2.0.

Posts #

Before version 2.0, when you wanted to get a collection of posts, the standard way was to use Timber::get_posts(), and Timber::get_post() to get a single post. But you could also use new Timber\Post() or new Timber\PostQuery().

We deprecated the possibility to instantiate objects directly. Instead, you should only use Timber::get_post() and Timber::get_posts().

Make sure you also read the new Posts Guide.

Timber::get_post() #

Use `Timber::get_post()` instead of `new Timber\Post()` #

It’s not possible anymore to directly instantiate a post with new Timber\Post(). Instead, you always need to use Timber::get_post() and pass in the ID of the post.

single.php

// Figure out post to get from current query.
$post = Timber::get_post();

Any template

// Pass in a post ID to get a particular post.
$post = Timber::get_post(56);

Updated function signature for `Timber::get_post()` #

We updated the function parameters for Timber::get_post().

🚫 Before

function get_post($query = false, $PostClass = 'Timber\Post')
{
};

✅ Now

function get_post(mixed $query = false, array $options = [])
{
};

We deprecated the $PostClass parameter. If you want to control the class your post should be instantiated with, use a Class Map filter. Instead, we now have an $options array.

Changed return type `Timber::get_post()` on failure #

Timber::get_post() returned false if no post could be found in 1.x. Now, that function will return null if no post could be found. We recommend using null instead of false for when no objects are found to match modern PHP practices.

Timber::get_posts() #

Use `Timber::get_posts()` instead of `new Timber\PostQuery()` #

🚫 Before

$query = [
    'post_type' => 'book',
    'posts_per_page' => 10,
    'post_status' => 'publish',
];

$latest_books = new Timber\PostQuery($query);

✅ Now

$query = [
    'post_type' => 'book',
    'posts_per_page' => 10,
    'post_status' => 'publish',
];

$latest_books = Timber::get_posts($query);

foreach ($latest_books->to_array() as $book) {
    // Do something.
}

Use an array instead of query strings in `Timber::get_posts()` #

It will no longer be possible to pass in arguments to Timber::get_posts() as a query string. Instead, you will have to use the array notation.

🚫 Before

Timber::get_posts('post_type=article');

✅ Now

Timber::get_posts([
    'post_type' => 'article',
]);

Updated function signature for `Timber::get_posts()` #

We updated the function parameters for Timber::get_posts().

🚫 Before

function get_posts($query = false, $PostClass = 'Timber\Post', $return_collection = false)
{
}

✅ Now

function get_posts(array $query, array $options = [])
{
}

The function still accepts the $query parameters as the first argument. Most of your queries will still work.

The following two parameters were removed:

$PostClass – You can’t directly pass the class to instantiate the object with anymore. Instead, you will have to use a Class Map filter.
$return_collection – You can’t tell the function whether it should return a Timber\PostCollection or an array of posts. It will always return an object implementing Timber\PostCollectionInterface. But you can always convert to collection to posts when you use to_array():

$posts_as_array = Timber::get_posts()->to_array();

🚫 Before

$args = [
    'post_type' => 'book',
    'posts_per_page' => 10,
    'post_status' => 'publish',
];

$latest_books_collection = Timber::get_posts($args, 'Book', true);
$latest_books_array = Timber::get_posts($args, 'Book');

✅ Now

$args = [
    'post_type' => 'book',
    'posts_per_page' => 10,
    'post_status' => 'publish',
];

$latest_books_collection = Timber::get_posts($args);
$latest_books_array = Timber::get_posts($args)->to_array();

The new $options parameter can be used to pass in options for the query. Check out the documentation for Timber::get_posts() to see all options.

Post queries in Twig #

You can run post queries in Twig. Pass the parameters in an argument hash (in Twig, key-value arrays are called hashes, and you use curly braces {} instead of brackets [] for them).

{# Hash notation #}
{% set posts = get_posts({
    post_type: 'post',
    post_status: 'publish',
    posts_per_page: 10
}) %}
{% if posts is not empty %}
    <ul>
        {% for post in posts %}
            <li><a href="{{ post.link }}">{{ post.title }}</a></li>
        {% endfor %}
    </ul>
{% endif %}

We still recommend you to run queries and prepare posts in PHP and not in Twig. But sometimes this is not possible when you don’t have access to the relevant PHP files, but only to Twig.

Post Collections #

We added some documentation about how to work with Post Collections, which are returned when you use Timber::get_posts().

Make sure you also read about the Laziness of posts.

Post Serialization #

When converting post data to JSON, for example to use post data in JavaScript, then we talk about Serialization. We added some documentation for that.

Terms #

Similar to posts, when you wanted to get a Timber term object before version 2.0, you could either use Timber::get_term() or new Timber\Term(). Now, instantiating Timber\Term directly doesn’t work anymore. You will always have to use Timber::get_term().

Make sure you also read the new Terms Guide.

Timber::get_term() #

Use `Timber::get_term()` instead of `new Timber\Term()` #

It’s not possible anymore to directly instantiate a term with new Timber\Term(). Instead, you always need to use Timber::get_term() and pass in the ID of the term.

// Pass in a term ID (or a WP_Term object) to get a particular term.
$term = Timber::get_term(17);

Updated function signature for `Timber::get_term()` #

We updated the function parameters for Timber::get_term().

🚫 Before

function get_term($term, $taxonomy = 'post_tag', $TermClass = 'Timber\Term')
{
};

✅ Now

function get_term($term = null)
{
};

We removed the $taxonomy parameter. Timber needs the ID of a term or a WP_Term object. It can figure out the taxonomy itself.
We removed the $TermClass parameter. If you want to control the class your term should be instantiated with, use a Term Class Map filter.

Removed edge case logic #

When you use Timber::get_term() without any parameter, Timber returns the queried term if the queried object is a term.

There was a hidden logic in Timber::get_term() for cases where there was no queried term: When the global query already had a tax_query definition that queried specific terms, Timber would return the first of these terms.

We removed that logic, because it could also lead to unexpected behavior.

Timber::get_terms() #

Updated function signature for `Timber::get_terms()` #

We updated the function parameters for Timber::get_terms().

🚫 Before

function get_terms($args = null, $maybe_args = [], $TermClass = 'Timber\Term')
{
};

✅ Now

function get_terms($args = null, array $options = [])
{
};

The function still accepts an $args parameter where you pass in the same arguments that you would pass to WP_Term_Query(). Most of your calls to Timber::get_terms() should still work the same.
The $options parameter is not used yet, but it might be used in the future.
We removed the $TermClass parameter. If you want to control the class your term should be instantiated with, use a Term Class Map filter.

Updated default query parameters for `Timber::get_terms()` #

Before Timber 2.0, we set the default argument hide_empty to false in the term query, which is not what WordPress does by default. WordPress always hides empty terms by default in term queries. For version 2, we don’t change these defaults and follow what WordPress does.

If you need empty terms, you need to explicitly set hide_empty to false.

$terms = Timber::get_terms([
    'taxonomy' => 'category',
    'hide_empty' => false,
]);

Comments #

To get a Timber comment object before version 2.0, you would use new Timber\Comment( $comment_id ). We removed the possibility to instantiate comment objects directly. You will always have to use the new Timber::get_comment() function.

🚫 Before

$comment = new Timber\Comment($comment_id);

✅ Now

$comment = Timber::get_comment($comment_id);

Menus #

Before version 2.0, when you wanted to get a menu, the standard way was to use new Timber\Menu(). We removed the possibility to instantiate menu objects directly. Instead, you should only use the new Timber::get_menu() function.

🚫 Before

$menu = new Timber\Menu('primary');

✅ Now

$menu = Timber::get_menu('primary');

A parameter is always required #

Before 2.0, you could pass in nothing to the constructor of Timber\Menu to get the first menu Timber found. We removed the possibility to pass in nothing when getting a menu because it led to confusing cases.

🚫 Before

This will cause an error.

$menu = new Timber\Menu();

✅ Now

Always pass a parameter.

$menu = Timber::get_menu('primary');

Previously, if you didn’t provide a parameter to Timber\Menu() and didn’t have any menus registered, Timber would build a menu from your existing pages. To achieve this same functionality, you must now use the new Timber::get_pages_menu() function.

🚫 Before

$menu = new Timber\Menu();

✅ Now

$menu = Timber::get_pages_menu();

If Timber::get_menu() can’t find a menu with the parameters you used, it will now return null.

Users #

To get a Timber user object before version 2.0, you would use new Timber\User( $user_id ). We removed the possibility to instantiate user objects directly. You will always have to use the new Timber::get_user() function.

🚫 Before

$user = new Timber\User($user_id);

✅ Now

$user = Timber::get_user($user_id);

Context #

Global context #

The context variables {{ wp_head }} and {{ wp_footer }} were removed definitely from the global context. Use {{ function('wp_head') }} and {{ function('wp_footer') }} in your Twig template directly.

Template context #

Version 2.0 introduces the concept of template contexts for Timber. This means that Timber will automatically set different variables like post in your context for singular templates and posts and maybe term or author for archive templates. Check out the section in the Context Guide for an overview.

Through the context, compatibility for third party plugins will be improved as well. Refer to the new Context Guide to learn more.

In short:

If you use $context['post'] = Timber::get_post() or $context['posts'] = Timber::get_posts() in your template files, you can probably omit these, because the context will do this for you. You might also benefit from better compatibility with third party plugins, because for singular templates, Timber will handle certain globals and hooks when setting up post.
If you decide to still use $context['post'] = … in your template file, then you should to set up your post through $context['post']->setup(). The setup() function improves compatibility with third-party plugins.
It’s now possible to overwrite the default arguments that are passed to the default query for posts.
When you need the global context in partials, then use Timber::context_global() to only load the global context.

Passing variables directly to context #

It’s now possible to pass data directly to Timber::context().

Here’s an example: Instead of setting a posts variable in $context after you’ve called Timber::context(), you can pass an associative array with a posts key and the same value to the Timber::context() function:

Still correct

$context = Timber::context();

$context['posts'] = Timber::get_posts([
        'post_type' => 'book',
        'posts_per_page' => -1,
        'post_status' => 'publish',
]);

Timber::render('archive.twig', $context);

Another way to do it

$context = Timber::context( [
	'posts' => Timber::get_posts( [
        'post_type'      => 'book',
        'posts_per_page' => -1,
        'post_status'    => 'publish',
	],
] );

Timber::render( 'archive.twig', $context );

Twig #

Updated function names #

In Twig, you could use functions that were called the same as classes to convert objects or IDs of objects into Timber object. To have the same function names as in Timber’s public API, we’ve added the following functions:

{{ get_post() }}
{{ get_posts() }}
{{ get_attachment_by() }}
{{ get_term() }}
{{ get_terms() }}
{{ get_user() }}
{{ get_users() }}
{{ get_comment() }}
{{ get_comments() }}

The following functions are now deprecated:

Deprecated functions	Use one of these instead
`{{ TimberPost() }}` `{{ Post() }}`	`{{ get_post() }}` `{{ get_posts() }}`
`{{ TimberTerm() }}` `{{ Term() }}`	`{{ get_term() }}` `{{ get_terms() }}`
`{{ TimberImage() }}` `{{ Image() }}`	`{{ get_image() }}` `{{ get_post() }}` `{{ get_attachment() }}` `{{ get_attachment_by() }}` `{{ get_posts() }}`
`{{ TimberUser() }}` `{{ User() }}`	`{{ get_user() }}` `{{ get_users() }}`

Updated timber/twig filters #

In Timber 1.x, apart from timber/twig, we had various (non-official) filters to filter the Twig Environment.

timber/twig/functions
timber/twig/filters
timber/twig/escapers

You shouldn’t use any of those to add functionality to the Twig Environment (\Twig\Environment) anymore. In Timber 2.x, you should only use timber/twig to extend \Twig\Environment.

If you use any of the above filters to extend the Twig Environment, you’ll get a Call to a member function addFunction() on array or a Call to a member function addFilter() on array error.

Here’s how the filters are used in Timber 2.0:

Filter	Usage before	Usage now
`timber/twig`	Extend `\Twig\Environment`	Extend `\Twig\Environment`
`timber/twig/functions`	🚫 Extend `\Twig\Environment`	✅ Add/remove Twig functions
`timber/twig/filters`	🚫 Extend `\Twig\Environment`	✅ Add/remove Twig filters
`timber/twig/escapers`	🚫 Extend `\Twig\Environment`	✅ Add/remove Twig escapers

Check out the new Extending Twig Guide to learn more and see some examples.

Namespaced Twig locations #

You can now use namespaced Twig locations. Read more about this in the Template Locations Guide.

Better compatibility with Twig date functions #

Twig has a date filter as well as a date() function. Timber 2.0 has much better compatibility with this functionality than before. Now, you can use any of the functionality described in Twig’s documentation.

Timber will automatically load the timezone as well as the default date format from the WordPress settings when you work with dates in Twig. Even if it’s advised in the Twig documentation, you shouldn’t update the timezone in Twig (unless you know what you’re doing):

// Don’t do this!
$twig = new \Twig\Environment($loader);
$twig->getExtension(\Twig\Extension\CoreExtension::class)->setTimezone('Europe/Paris');

Also refer to the new Date/Time Guide for extended information on working with dates in Timber.

No context argument when calling actions in Twig #

In version 1.x of Timber, you would always get the context as a last argument in the hook function:

{% do action('my_action', 'foo') %}

add_action('my_action_with_args', 'my_function_with_args', 10, 3);

function my_function_with_args($foo, $post, $context)
{
    echo 'I say ' . $foo . '!';
    echo 'For the post with title ' . $context['post']->title();
}

In version 2.0, a context argument will no longer be passed to the hook function. Now, if you want anything from the template’s context, you’ll need to pass in the argument manually:

{% do action('my_action', 'foo', post) %}

add_action('my_action_with_args', 'my_function_with_args', 10, 2);

function my_function_with_args($foo, $post)
{
    echo 'I say ' . $foo . '!';
    echo 'For the post with title ' . $post->title();
}

Deprecated Twig filters #

The following Twig filters have been deprecated and will be removed in future versions of Timber:

|get_class
|print_r

In addition, the confusingly named (and non-functional) |get_type filter has been removed.

Twig deprecations #

Apart from the deprecations listed above, you should also consider the deprecations by Twig itself.

Deprecated features in Twig 2.x – Make sure you check out the deprecated features for Tags.
Deprecated features in Twig 3.x – Twig mainly removes all deprecated features in 2.x.

There are a couple we want to highlight:

Spaceless #

The spaceless tag is deprecated, you should use the apply tag using the spaceless filter instead.

🚫 Before

{% spaceless %}

{% endspaceless %}

✅ Now

{% apply spaceless %}

{% endapply %}

Filter tag #

The filter tag is deprecated. Use the apply tag in combination with apply_filters() instead.

🚫 Before

{% filter apply_filters('your_filter_name') %}

{% endapply %}

✅ Now

{% apply apply_filters('your_filter_name') %}

{% endapply %}

Meta #

Deprecating direct access to meta values #

In Timber 1.x, it was possible to access meta values via dynamic properties. For example, you could do:

{{ post.my_custom_field_name }}

This is no longer the recommended way to access meta values because there might be conflicts with existing Timber methods or properties. For example, if you named a custom field date and accessed it through {{ post.date }}, it wasn’t clear if you would get the posts’ date or the value for your custom field named date.

Access meta values through meta() #

The new recommended way to access meta values is through meta():

{{ post.meta('my_custom_field_name') }}

This way, your values will be filtered by third-party plugins like ACF.

Access raw meta values #

If you want to access the raw and unfiltered value directly from the database instead, you can use the new raw_meta() method:

{{ post.raw_meta('my_custom_field_name') }}

The custom property #

Maybe you were also used to use the $custom property on an object:

{{ post.custom.my_custom_field_name }}

This property was removed and you can no longer access meta values through it. It was only meant as a reference for you to see which meta values exist for an object when you use {{ dump() }} or var_dump(). To access the values, you should always use the meta('field_name') and raw_meta('field_name') methods. If you still need to know which meta values exist on an object, you can use meta() or raw_meta() without a field name:

{{ dump(post.meta()) }}
{{ dump(post.raw_meta()) }}

This is only recommended for development purposes, because it might affect your performance if you always request all values.

The meta() and raw_meta() methods work the same way for all Timber\Post, Timber\Term, Timber\User and Timber\Comment objects. You can read more about this in the Custom Fields Guide as well as the ACF Integrations Guide.

New classes #

New Attachment class #

Up until now, there was only a representation for WordPress image attachments in Timber. With version 2.0, we introduce a new Timber\Attachment class that represents WordPress attachments – including the ones that might not necessarily be images, like PDF files.

The Timber\Image class now extends the Timber\Attachment class. All your code should already be compatible with this change. But in the future, you could use the new Timber\Attachment class if you work with an attachment that is not an image.
We’ve added new methods for Timber\Attachment. See the section below.
To get attachments from attachment IDs in Twig, you can use {{ get_attachment(attachment_id) }}. Behind the curtains, Timber uses Class Maps to use the Timber\Image and Timber\Attachment classes for attachment posts.

New ExternalImage class #

With Timber 2.0, we differentiate between images that are WordPress attachments and "external" images that are loaded from a different location in your WordPress installation, for example from your theme folder.

Previously, when you used {{ Image(url).src }} in Twig, you could also provide a path or URL to an external image. Now, you should use {{ get_external_image(url).src }}.

With the new Timber::get_external_image() function, you can load an external image in PHP.

New PagesMenu class #

To handle cases where you wanted to build a menu from your existing pages separately, we added a Timber\PagesMenu class that will be used when you use the new Timber::get_pages_menu() function.

Deprecated functions and variables #

The following functions are being deprecated and will be removed in a future version of Timber.

Timber\Timber #

get_context() - use context() instead.
Timber::$autoescape – use the timber/twig/environment/options filter instead.
Timber::$twig_cache – use the timber/twig/environment/options filter instead.
Timber::$cache – use the timber/twig/environment/options filter instead.

Timber\Post #

get_preview() - use excerpt() instead.
get_field() - use meta() instead.
import_field() - use meta() instead.
preview() - use excerpt() instead.
update() - use WordPress core’s update_post_meta() instead.

Timber\PostQuery #

get_query(), use query() instead.

Timber\Image and Timber\Attachment #

get_pathinfo() – use pathinfo() instead.
get_dimensions() – use width() or height() instead.
get_dimensions_loaded() – use width() or height() instead.
get_dimension() – use width() or height() instead.
get_dimension_loaded() – use width() or height() instead.
get_post_custom() – use meta() instead.

Timber\Term #

get_children() – use children() instead.
get_edit_url() – use edit_link() instead.
get_field() – use meta() instead.
get_meta_field() – use meta() instead.
get_posts() – use posts() instead.
update() - use WordPress core’s update_metadata() instead.

Timber\Comment #

get_field() - use {{ comment.meta('my_field_name') }} instead
get_meta_field() - use {{ comment.meta('my_field_name') }} instead
update() - use WordPress core’s update_metadata() instead.

Timber\MenuItem #

external() – use {{ item.is_external }} instead.
get_children() – use {{ item.children }} instead.
get_field() – use {{ item.meta }} instead.

Timber\User #

get_field() – use {{ user.meta('my_field_name') }} instead.
get_meta() – use {{ user.meta('my_field_name') }} instead.
get_meta_field() – use {{ user.meta('my_field_name') }} instead.

Timber\Site #

$pingback property – use $pingback_url.
meta() – use option() instead.
update() – use WordPress core’s update_blog_option() instead.
url() – use link() instead.

Timber\Archives #

get_items() – use items() instead.

Timber\Twig #

intl_date(), use Timber\DateTimeHelper::wp_date() instead.
time_ago(), use DateTimeHelper::time_ago() instead.

Timber\Loader #

template_exists() – No longer used internally.

Timber\LocationManager #

get_locations_user() – Use add_filter( 'timber/locations', $locations ) instead

Removed functions and properties #

The following functions and properties were removed from the codebase, either because they were already deprecated or because they’re not used anymore.

Timber\Timber #

add_route() - The routes feature was completely removed in 2.0.
get_pagination() – Use {{ posts.pagination }} instead. Follow the Pagination Guide for more information.

Timber\Site #

get_link(), use {{ site.link }} instead
get_url(), use {{ site.link }} instead

Timber\Post #

audio(), use get_media_embedded_in_content() instead.
get_author() – use {{ post.author }} instead
get_categories() – use {{ post.categories }} instead
get_category() – use {{ post.category }} instead
get_children() – use {{ post.children }} instead
get_comment_count() – use {{ post.comment_count }} instead
get_comments() – use {{ post.comments }} instead
get_content() – use {{ post.content }} instead
get_edit_url() – use link() instead
get_format() – use {{ post.format }} instead
get_image() – use {{ get_image(post.meta('my_image')) }} or {{ get_attachment(post.meta('my_file')) }} instead
get_link() – use {{ post.link }} instead
get_modified_author() – use {{ post.modified_author }} instead
get_modified_date() – use {{ post.modified_date }} instead
get_modified_time() – use {{ post.modified_time }} instead
get_next() – use {{ post.next }} instead
get_pagination() – use {{ post.pagination }} instead
get_parent() – use {{ post.parent }} instead
get_path() – use {{ post.path }} instead
get_permalink() – use {{ post.link }} instead
get_post_id_by_name()
get_post_type() – use {{ post.type() }} instead
get_prev() – use {{ post.prev }} instead
get_tags() – use {{ post.tags }} instead
get_terms() – use {{ post.term }} instead
get_thumbnail() – use {{ post.thumbnail }} instead
get_title() – use {{ post.title }} instead
init() – no replacement.
permalink() – use {{ post.link }} instead
prepare_post_info()
video(), use get_media_embedded_in_content() instead.

Timber\Term #

get_link() – use {{ term.link }} instead
get_path() – use {{ term.path }} instead
get_term_from_query() - use Timber::get_term() instead

Timber\Image #

init() – only relevant if you’ve extended the Timber\Image class
determine_id() – only relevant if you’ve extended the Timber\Image class
get_attachment_info() – use get_info() instead
get_src() – use {{ image.src }} instead
get_url() – use {{ image.src }} instead
url() – use {{ image.src }} instead
is_image() – without replacement. Timber now checks whether a post is an image if you use Timber::get_post() or Timber::get_image() and only returns a Timber\Image object for attachments that are images.
$caption property – use caption() method instead. You can still use {{ image.caption }} in Twig. In PHP $image->caption also still works because magic properties will automatically resolve to $image->caption().
$sizes property - use sizes() method instead. You can still use {{ image.sizes }} in Twig. In PHP $image->sizes also still works because magic properties will automatically resolve to $image->sizes().

Timber\MenuItem #

get_link() – use {{ item.link }} instead
get_path() – use {{ item.path }} instead
permalink() – use {{ item.link }} instead
type() – use the the MenuItem::$type property instead. In Twig, this is still the same: {{ item.type }}.

Timber\Comment #

$PostClass property – use Class Maps instead.

Timber\CommentThread #

$CommentClass property – use Class Maps instead.

Timber\User #

$name property – use name() method instead. You can still use {{ user.name }} in Twig.
$first_name property – use {{ user.meta('first_name') }} instead.
$last_name property – use {{ user.meta('last_name') }} instead.
$description property – use {{ user.meta('description') }} instead.

Timber\Helper #

function_wrapper() – use {{ function( 'function_to_call' ) }} instead
trim_words() – use TextHelper::trim_words() instead
close_tags() – use TextHelper::close_tags() instead
get_comment_form() – use {{ function('comment_form') }} instead
paginate_links() – use Pagination::paginate_links() instead
get_current_url() – use Timber\URLHelper::get_current_url() instead
filter_array() – use array_filter() or Timber\Helper::wp_list_filter() instead.

Timber\TextHelper #

starts_with() - use str_starts_with() instead.
ends_with() - use str_ends_with() instead.

Timber\Integration\Command #

The whole Timber\Integration\Command class was removed. Its methods were moved over to the Timber\Cache\Cleaner class.

clear_cache(), use Timber\Cache\Cleaner::clear_cache() instead.
clear_cache_timber(), use Timber\Cache\Cleaner::clear_cache_timber() instead.
clear_cache_twig(), use Timber\Cache\Cleaner::clear_cache_twig() instead.

New functions #

Timber\Timber

context_global() - Gets the global context.
context_post() - Gets post context for a singular template.
context_posts() - Gets posts context for an archive template.
get_attachment() – Gets an attachment.
get_attachment_by() – Gets an attachment by its URL or absolute file path.
get_menu() – Gets a menu object for a specific menu.
get_image() – Gets an image that is a WordPress attachment.
get_external_image() – Gets an image that is not a WordPress attachment.
get_pages_menu() – Gets a menu object built from your existing pages.
get_post_by() – Gets a post by title or slug.
get_term_by() – Gets a post by title or slug.
get_user() – Gets a single user.
get_users() – Gets one or more users as an array.
get_user_by() – Gets a user by field.

Timber\Post

raw_meta() – Gets a post meta value directly from the database.
wp_object() - Gets the underlying WordPress Core object.

Timber\Term

raw_meta() – Gets a term meta value directly from the database.
wp_object() - Gets the underlying WordPress Core object.

Timber\User

raw_meta() – Gets a user meta value directly from the database.
wp_object() - Gets the underlying WordPress Core object.
edit_link() – Gets the edit link for a user if the current user has the correct rights.

Timber\Comment

raw_meta() – Gets a comment meta value directly from the database.
wp_object() - Gets the underlying WordPress Core object.
edit_link() - Gets the edit link for a comment if the current user has the correct rights.

Timber\Menu

current_item() – Gets the current menu item. Read more about this in the functions’s documentation or the Menu Guide.
current_top_level_item() – Gets the top level parent of the current menu item.
wp_object() - Gets the underlying WordPress Core object.

Timber\MenuItem

target() – Gets the target of a menu item according to the «Open in new tab» option in the menu item options.
is_target_blank() – Checks whether the «Open in new tab» option checked in the menu item options in the backend.
wp_object() - Gets the underlying WordPress Core object.

Timber\Attachment

size() - Gets the filesize of an attachment in bytes.
size_raw() - Gets the filesize of an attachment in a human-readable format. E.g. 16 KB instead of 16555 bytes.
extension() - Gets the extension of the attached file.

Timber\User

wp_object() - Gets the underlying WordPress Core object.

New and updated functions #

Timber\Timber

get_post_by() – Gets a post by post slug or post title.

Timber\Post

children() – We removed the $child_post_class parameter in this function. Use Class Maps instead to control which class to instantiate child posts with.
comments() – We removed the $CommentClass parameter in this function. Use Class Maps instead to control which class to instantiate child posts with.

Timber\Cache\Cleaner

clear_cache() - We remove the possibility to pass an array to that function. Now, only strings are accepted.

Timber\Post::terms() #

The Timber\Term::terms() function already supported using an array of query arguments. But to make it more consistent with how other functions are used in Timber, we changed the signature to use two parameters: $query_args and $options.

Function Signature

// 🚫 Before
function terms($args = [], $merge = true, $term_class = '')
{
};

// ✅ Now
function terms($query_args = [], $options = [])
{
};

PHP

// 🚫 Before
$terms = $post->terms('category');

// ✅ Now
$terms = $post->terms([
    'taxonomy' => 'category',
]);

// 🚫 Before
$terms = $post->terms([
    'query' => [
        'taxonomy' => 'custom_tax',
        'orderby' => 'count',
    ],
    'merge' => false,
]);

// ✅ Now
$terms = $post->terms([
    'taxonomy' => 'custom_tax',
    'orderby' => 'count',
], [
    'merge' => false,
]);

Twig

{# 🚫 Before #}
{% for term in post.terms('category') %}

{# ✅ Now #}
{% for term in post.terms({ taxonomy: 'category' }) %}

{# or #}

{# ✅ Now #}
{% for term in post.terms({
    query: {
        taxonomy: 'custom_tax',
        orderby: 'count'
    },
    merge: false
})}

Timber\Post::get_info() #

We changed the function signature for the get_info() function. This function is responsible for the properties that are imported in the Timber\Post object from a WP_Post object.

This change is only relevant if you extend the Timber\Post class and add a custom get_info() method.

Before, the function got a post ID as a parameter and returned a WP_Post object. Now, the function gets an array of post data and returns an updated array with data that will then be imported.

Before

protected function get_info($post_id)
{

}

Now

protected function get_info(array $data) : array
{
    // Access the original post through $this->wp_object.

    return $data;
}

Timber\Term::posts() #

We changed the function parameters for the Timber\Term::posts() function to better support different use cases. Basically, you’ll use the same query parameters that you already know from WP_Query.

Function Signature

// 🚫 Before
function posts($numberposts_or_args = 10, $post_type_or_class = 'any', $post_class = '')
{
};

// ✅ Now
function posts($query_args = [])
{
};

🚫 Old usage

In PHP:

$genre->posts(-1, 'book');

And in Twig:

{% for book in genre.posts(-1, 'book) %}

✅ New usage

In PHP:

$genre->posts([
    'post_type' => 'book',
    'post_per_page' => -1,
    'orderby' => 'menu_order',
]);

And in Twig:

{% for book in genre.posts({
    post_type: 'book',
    posts_per_page: -1,
    orderby: 'menu_order'
}) %}

You can still also pass an integer as the sole argument, to tell it how many posts you want.

$genre->posts(3);

This is equivalent to:

$genre->posts([
    'posts_per_page' => 3,
    'post_type' => 'any',
]);

Timber\URLHelper #

`Timber\URLHelper::get_params()` #

The Timber\URLHelper::get_params() method now returns false if passed an index that does not exist, whereas before it returned null in that case. This is for better consistency with other core API methods and only affects code using === or equivalent checks on return values from this method.

`Timber\URLHelper::is_local()` and `Timber\URLHelper::is_external()` #

The Timber\URLHelper::is_local() and Timber\URLHelper::is_external() methods were updated to fix some bugs with false positives, e.g. when an URL appeared as part of the query. The methods will now analyze the hostname instead of just checking the whole URL for the site’s URL.

Post Excerpts #

Excerpt instead of Preview #

We renamed the Timber\PostPreview class to Timber\PostExcerpt and also changed all instances of the term "preview" to "excerpt". The reason for this change is that the term "preview" in WordPress is mainly used for previewing a post before you save changes in the admin. For the short texts that are used in post teasers, the term "excerpt" is used. We wanted to follow the WordPress terminology here.

For this, we…

Renamed the Timber\PostPreview class to Timber\PostExcerpt.
Added a Timber\Post::excerpt() function that you should use instead of Timber\Post::preview().
Changed filter names.

Filter the defaults #

There’s a new timber/post/excerpt/defaults filter that can be used to update default options for excerpts, including always_add_read_more and always_add_end.

add_filter('timber/post/excerpt/defaults', function ($defaults) {
    // Only add a read more link if the post content isn’t longer than the excerpt.
    $defaults['always_add_read_more'] = false;

    // Set a default character limit.
    $defaults['words'] = 240;

    return $defaults;
});

`post.excerpt` takes arguments in array/hash notation #

The {{ post.excerpt }} function was added as a replacement for {{ post.preview }}. When using {{ post.preview }}, you could pass in arguments by chaining them. It’s now possible to pass in arguments as an array in PHP or in hash style in Twig. This finally cleans up how the previews of posts are handled. Here’s an example:

PHP

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

Twig

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

Hooks #

In version 1.0, we already introduced some filters and actions that were namespaced with a timber/ prefix. In version 2.0, we refactored all filters to have the same naming standard. If you still use an old action or filter, you will see a warning with the name of the new hook. See the Hooks section in the documentation that lists all the current hooks. There, you’ll also see which hooks are deprecated.

Deprecated hooks #

You should update the following hooks because they will be removed in a future version of Timber. We use apply_filters_deprecated(), so you should get a proper warning when WP_DEBUG is set to true.

Timber\Timber

timber_render_file, use timber/render/file instead
timber_render_data, use timber/render/data instead
timber_compile_file, use timber/compile/file instead
timber_compile_data, use timber/compile/data instead
timber_compile_done, use timber/compile/done instead

Timber\Post

timber_post_get_meta_field_pre, use timber/post/pre_meta instead
timber_post_get_meta_pre, use timber/post/pre_get instead
timber_post_get_meta_field, use timber/post/meta instead
timber_post_get_meta, use timber/post/meta instead
Timber\PostClassMap, use timber/post/classmap instead

Timber\PostGetter

Timber\PostClassMap, use timber/post/classmap

Timber\PostPreview

timber/post/preview/read_more_class, use timber/post/excerpt/read_more_class instead
timber/post/get_preview/read_more_link, use timber/post/excerpt/read_more_link instead

Timber\Term

timber/term/meta/field, use timber/term/meta instead
timber_term_get_meta_field, use timber/term/meta instead
timber_term_get_meta, use timber/term/meta instead

Timber\Comment

timber_comment_get_meta_field_pre, use timber/comment/pre_meta instead
timber_comment_get_meta_pre, use timber/comment/pre_meta instead
timber_comment_get_meta_field, use timber/comment/meta instead
timber_comment_get_meta, use timber/comment/meta instead

Timber\User

timber_user_get_meta_field_pre, use timber/user/pre_meta instead
timber_user_get_meta_pre, use timber/user/pre_meta instead
timber_user_get_meta_field, use timber/user/meta instead
timber_user_get_meta, use timber/user/meta instead

Timber\Site

timber_site_set_meta, use timber/site/update_option instead

Timber\Loader

timber/cache/location, use an absolute path in the cache option in the timber/twig/environment/options filter instead.
timber/loader/paths, use timber/locations instead

Timber\URLHelper

The following filter names have changed to match the WordPress naming convention for hooks, which says that hooks should be all lowercase:

timber/URLHelper/url_to_file_system/path, use timber/url_helper/url_to_file_system/path instead
timber/URLHelper/file_system_to_url, use timber/url_helper/file_system_to_url instead
timber/URLHelper/get_content_subdir/home_url, use timber/url_helper/get_content_subdir/home_url instead

Deprecated without replacement #

The following filters were deprecated without a replacement and will be removed in the next major version:

The filters timber_term_set_meta and timber/term/meta/set were deprecated. They were used by Term::update(), which is now deprecated as well (without a replacement).

timber/term/meta #

If you’ve used timber/term/meta before, you might have to switch to timer/term/get_meta_fields. The timber/term/meta filter was introduced in 2.0 to be used instead of timber/term/meta/field and timber_term_get_meta_field. However, a filter timber/term/meta already existed in Term::get_meta_values() for version 1.0 and was renamed to timber/term/get_meta_fields to match the new naming conventions.

Removed hooks #

The following filters were removed without a replacement:

Timber\PostClassMap – use the Post Class Map instead.
timber/get_posts/mirror_wp_get_posts – This filter was used so that Timber::get_posts() mimics the behavior of WordPress’s get_posts() function. We removed it because Timber::get_posts() is the new official API. If you want the same behavior, there are arguments that you can pass to this function.
timber_post_getter_get_posts – Removed because the Timber\PostGetter class doesn’t exist anymore.
timber/class/posts_iterator – Removed because the Timber\PostCollection class doesn’t exist anymore. Use custom Post::setup() and Post::teardown() methods instead. Read more about this in the Better compatibility with plugins section.

New hooks #

We added new hooks that let you filter things you couldn’t filter before:

timber/term/classmap
timber/menu/classmap
timber/menuitem/class
timber/pages_menu/class
timber/user/class
timber/comment/classmap
timber/twig/environment/options

Sideloaded/external images #

We changed the folder for images that are loaded from external URLs through Timber\ImageHelper::sideload_image() or when you use the |resize filter.

They will now be loaded to a folder named external in your uploads folder. We added this change because when you use a year-month-based folder structure, sideloaded images would be downloaded again each month.

You can control this behavior using the timber/sideload_image/subdir filter.

We also integrated sideloading images in the new Timber::get_external_image() function. If you provide it with an external image, it will sideload the image and return a Timber\ExternalImage object to easily work with it.

Escaping #

While Twig has escaping enabled by default, Timber doesn’t automatically enable escaping for Twig. To enable autoescaping in Timber 1.x, you would use Timber::$autoescape = true. The value true was deprecated for Twig 2.0, you now have to use html or another auto-escaping strategy instead. You’ll need to use the timber/twig/environment/options filter:

add_filter('timber/twig/environment/options', function ($options) {
    $options['autoescape'] = 'html';

    return $options;
});

Read more about this in the Escaping Guide.

Integrations #

There’s a new way how integrations are initialized internally. Timber uses a new timber/integrations filter to get all integrations it should init. Each integration uses an interface with a should_init() and an init() method that Timber can use to check whether an integration should be initialized before it actually initializes an integration.

With that filter and the interface, it’s easier to add your own integrations and remove or replace existing Timber integrations. Read all about it in the new Custom Integrations Guide.

WP-CLI #

Timber already had an integration for WP-CLI in version 1, but only few people knew about it. It is now documented in the WP CLI Guide.

We updated the WP-CLI commands for Timber:

🚫 Before

wp timber clear_cache
wp timber clear_cache_timber
wp timber clear_cache_twig

✅ After

wp timber clear-cache
wp timber clear-cache timber
wp timber clear-cache twig

Documentation #

We added a couple of new guides that you may want to read through in addition to this Upgrade Guide:

Posts Guide
Terms Guide
Users Guide
Class Maps Guide
Context Guide
Custom Fields Guide, which is now decoupled from the ACF Integrations Guide.
Custom Integrations Guide
WP CLI Guide

Upgrade to 2.0

New requirements #

No more plugin support #

Initializing Timber #

Don’t use a $timber global #

Checking Timber’s version #

Removed functionality #

Removed Routes #

Removed Twig cache extension #

Removed Timber\Request class #

Namespaced class names #

Timber\Timber #

Twig classes #

An updated API to get Timber objects #

Factories #

Removed classes #

Better compatibility with plugins #

Posts #

Timber::get_post() #

Use Timber::get_post() instead of new Timber\Post() #

Updated function signature for Timber::get_post() #

Changed return type Timber::get_post() on failure #

Timber::get_posts() #

Use Timber::get_posts() instead of new Timber\PostQuery() #

Use an array instead of query strings in Timber::get_posts() #

Updated function signature for Timber::get_posts() #

Post queries in Twig #

Post Collections #

Post Serialization #

Terms #

Timber::get_term() #

Use Timber::get_term() instead of new Timber\Term() #

Updated function signature for Timber::get_term() #

Removed edge case logic #

Timber::get_terms() #

Updated function signature for Timber::get_terms() #

Updated default query parameters for Timber::get_terms() #

Comments #

Menus #

A parameter is always required #

The Pages Menu #

Users #

Context #

Global context #

Template context #

Passing variables directly to context #

Twig #

Updated function names #

Updated timber/twig filters #

Namespaced Twig locations #

Better compatibility with Twig date functions #

No context argument when calling actions in Twig #

Deprecated Twig filters #

Twig deprecations #

Spaceless #

Filter tag #

Meta #

Deprecating direct access to meta values #

Access meta values through meta() #

Access raw meta values #

The custom property #

New classes #

New Attachment class #

New ExternalImage class #

New PagesMenu class #

Deprecated functions and variables #

Timber\Timber #

Timber\Post #

Timber\PostQuery #

Timber\Image and Timber\Attachment #

Timber\Term #

Timber\Comment #

Timber\MenuItem #

Timber\User #

Timber\Site #

Timber\Archives #

Timber\Twig #

Timber\Loader #

Timber\LocationManager #

Removed functions and properties #

Don’t use a `$timber` global #

Removed `Timber\Request` class #

Use `Timber::get_post()` instead of `new Timber\Post()` #

Updated function signature for `Timber::get_post()` #

Changed return type `Timber::get_post()` on failure #

Use `Timber::get_posts()` instead of `new Timber\PostQuery()` #

Use an array instead of query strings in `Timber::get_posts()` #

Updated function signature for `Timber::get_posts()` #

Use `Timber::get_term()` instead of `new Timber\Term()` #

Updated function signature for `Timber::get_term()` #

Updated function signature for `Timber::get_terms()` #

Updated default query parameters for `Timber::get_terms()` #

`Timber\URLHelper::get_params()` #

`Timber\URLHelper::is_local()` and `Timber\URLHelper::is_external()` #

`post.excerpt` takes arguments in array/hash notation #