Upgrade to Timber 2.0 alpha


Some time ago the alpha version of Timber 2.0 got released. I decide to test it on WP Owls and see how complicated the upgrade process is and how many problems I’ll encounter.

LMS created by e-learning experts

Before you start

First of all, remember this is an alpha release – probably not everything will work correctly. The good news is, at least in my case, I didn’t encounter any problems, although WP Owls is a small and simple site.
Second – remember to read the update guide here  
And third – install Query Monitor and set WP_DEBUG to true. Thanks to this you will spot all the errors much faster.


If you are using the Timber plugin then you have to remove it first and install the Composer version. Why? The plugin version was always a bit troublesome and the easiest solution was just to eliminate the problem.
If you are already using Composer, that just change the version to 2.0.0-alpha.1.

Let’s start with a… critical error

It wasn’t a surprise, because some functions, classes, and method names got changed. In my case, the problems were related to:

  • TimberMenu is now Timber\Menu
  • Twig\Twig_Filter is now Twig\TwigFilter

Check this page https://timber.github.io/docs/v2/upgrade-guides/2.0/#namespaced-class-names for a complete list of such changes.


Now it’s time to remove or change all deprecated functions, variables, or filters. I had some luck because in my case I only had to change three things:

  • Timber::get_context() became Timber::context() – it’s also worth to mention that there is a new method Timber::context_global(), which stores only global values
  • filter timber_context became timber\context
  • Image function changed into get_post() or get_image(). It may sound a bit weird, but if you look under the hood it you’ll see it has a lot of sense.


I mentioned before that context changed a bit and I must say those changes are great.
First of all, we always have access to some variables groups:

  • site – here you can find all data related to our site
  • request – this gives you access to $_GET and $_POST
  • theme – here you’ll find variables related to the active theme
  • user – it shows all the logged user data 

Thanks to this I could get rid of a variable that used I to have access to $_POST.
Another thing worth mentioning is the fact that post (on singular pages) and posts (on archives) are automatically added to the context. Thanks to this I could remove this line from all templates:

$context['posts'] = Timber::get_posts();

It doesn’t look like a big change, but it’s another line less in our code.

Class mapping

Class mapping is the thing I love in Timber 2.0. 
In the previous version we had to write something like this each time:

$context['other_posts'] = Timber::get_posts( $args, 'OwlPost' );

where OwlPost was the class that extended the default post class. It worked but we had to remember to add this parameter each time.
Now, thanks to class mapping, we can solve it a bit easier:

$context['other_posts'] = Timber::get_posts( $args );

  function( $classmap ) {
      $custom_classmap = array(
          'post' => OwlPost::class,
      return array_merge( $classmap, $custom_classmap );

thanks to the filter we set mapping which class extends which custom post type.

LMS created by e-learning experts

Cache and variables

It’s also nice that setting all variables takes place with one filter (timber/twig/environment/options) – this means that now we use:

    function( $options ) {
        $options['cache'] = true;
        return $options;

instead of:

Timber::$cache = true;

Let’s wrap it up

Overall I love the changes that were introduced in Timber 2.0. For sure I’ll try to migrate all my projects to it when the beta version will be ready.

There are lots of changes that prevent us from repeating the same code over and over.

Also, based on my experiment, I can say that the migration process is quite simple. 

The only thing left to do is to test further, post issues, and wait for a stable version. 

If you like this article, don't forget to share it.