Roadmap for Timber 2.0

[gchtr]

This is an overview issue for the release of version 2.0 of Timber. If you find questions about the release of Timber 2.0, guide them here.

Roadmap

The next steps for a 2.0 release are:

• Release second beta 2.0.0-beta.2 by the end of this week
• Work through open pull requests and issues. Triage issues and pull requests that are not critical for the 2.0 release.
• First release candidate 2.0.0-rc.1 by June/July 2023
• Release Timber 2.0 one to two months after developers could test out the release candidate.
  🚀 Check out the Release notes.

The past has shown us that it’s difficult to predict an exact ETA. And with our limited resources, we don’t want to make promises we can’t keep. But let’s work towards a 2.0 release by being strict about what we really need for a 2.0 release and what we can postpone for later.

Help is welcome from everyone, also developers who are not maintainers. If you can provide insights, spot issues in the pull requests and comment on these, you’ll help us move the project forward.

Pull requests

The following pull requests need to be reviewed and resolved.

• 2.x Remove unneeded Timber\Image::is_image() method #2669
• Fix PostFactory::is_image incorrectly using wp_check_filetype #2730
• 2.x Make object constructors final #2660
• 2.x Fix PHPStan issues on level 1 #2667
• 2.x Fix PHPStan issues on level 2 #2668
• Fix custom field test #2749
• Remove audio & video methods from Post #2750
• Remove unused private property #2751
• 2.x cs imports #2700
• Refactor file models #2753

For each of these pull requests we should decide whether we can solve them in the future or whether we really need to solve them for a first 2.0 release. By "future", we mean that we can decide whether:

• The issue can be resolved in a minor version of Timber 2.x, so 2.1 or 2.2, etc.
• The issue will have to wait for Timber 3.x.

Postponed issues and pull requests

• 2.x Fix menu location compatibility with WPML #2733 (postponed to 2.x Future)
• Timber 2.x - ImageHelper::theme_url_to_dir() returns an invalid path when theme template is theme-name/theme #2453 (postponed to 2.x Future)
• 2.x Add ImageHelper filters to customize paths #2725 (postponed to 2.x Future)
• [BUG] symfony/cache-extra and timber 2, cache method unclear #2762 (postponed to 2.x Future)

Outstanding issues

• Update Starter Theme for 2.x #1784 – Is possibly resolved already and can be closed.
• [BUG] URLHelper::is_external() false-positive #2766
• [BUG] toWebP() causes Uncaught TypeError: imageistruecolor(): Argument #1 ($image) must be of type GdImage, null given Error #2771
• Link Checker Report #2745

Issues with patches

This issues have patches and will be resolved when their corresponding pull requests are resolved.

• Source code contains to be resolved issues "todos" #2626
• [BUG] Deprecation Notice implicit conversion from float to int in ImageDimensions.php #2772
• is_image() function not working with URL params appended to an image src #2444
• Timezone Errors with post dates #2737
• Test code snippets in Getting Started section #2278

After release

• Make the 2.x branch the default one
• Make a 1.x branch
• Undo 2.x Add note about installing the release candidate #2796. See 2.x Prepare 2.0 release #2829
• Make the v2 docs the default docs
• Make a change in https://timber.github.io/docs/getting-started/setup/ on how to install the v1 version for legacy purposes. See 2.x Prepare 2.0 release #2829.
• Update the upgrade guide to link to the migration guide to switch to the composer version of Timber v1
• Update readme.md in both branches to refer to eachother. As an example see:

Example for 1.x branch:

Example for main (2.x) branch:

[nlemoine]

I'm also adding links errors in docs, at least for 2.0:

• Link Checker Report #2742

[Levdbas]

PR for #2742 in #2743

[jarednova]

Amazing, this is exciting stuff. It's really important to highlight: what we really need for a 2.0 release and what we can postpone for later. This provides a clear and focused mapping to get us the rest of the way there!

[gchtr]

Update:

• The second beta is released: https://github.com/timber/timber/releases/tag/2.0.0-beta.2.
• A new build of the docs is published on https://timber.github.io/docs/.

[rmens]

Awesome to see a roadmap. Very excited for the first RC and ready to report bugs when upgrading a site from Timber 1 to Timber 2 🥳

[piyushchauhan2011]

Excited for RC release 🚀

[gchtr]

We’re glad that we could finish the first steps towards the final release as planned.

• The first release candidate of Timber 2.0 is out: https://github.com/timber/timber/releases/tag/2.0.0-rc.1! 🥳
• Docs are updated with the latest changes on timber.github.io/docs.

[xavivars]

This is such a massive step forward! Thanks a lot everyone for working so hard on this

[herrschuessler]

Very excited indeed!

Is there an upgrade guide anywhere?

[xavivars]

https://timber.github.io/docs/v2/upgrade-guides/2.0/

[herrschuessler]

I'v upgraded 6-7 dev sites running PHP 8.1 and 8.2 to Timber 2.0 RC2 in the last week and so far (thanks to the detailed upgrade guide), everything is going very smooth, no issues at all. 👍

[nlemoine]

That's great to know! thanks for your feedback :)

[Levdbas]

Updated my parent/child theme framework as well without any issues. I am going to test this in some upcoming projects to see if I run into any other issue.

[jrathert]

I updated my theme today with 2.0.0-rc.1. Everything went quite smooth, although it took me some time to understand the new handling of ACF repeaters, relationships and flexible content field. I have a quite elaborate ACF structure of layouts and field mixed with CPTs etc. Esp. the .image property of what actually I was sure is already a picture was tricky... But after a bit of thinking, it all makes sense to me. Thanks for the great work!

Just one annoying observation: During debugging, I recognized a warning in my logs:

PHP Notice: [ Timber ] {{ site.meta() }} is deprecated since Timber version 2.0.0! Use {{ site.option() }} instead. in /var/www/html/wp-content/themes/swkoeln/vendor/timber/timber/src/Helper.php on line 441

I did not find any reference to site.meta in my code, and only after adding a debug_print_backtrace() into timber code I realized it seems it is actually caused by Timber itself (see backtrace below my post)?! Not sure though, I am a bit of a PHP newbie...

Thanks again for the good work!

Jonas

Backtrace:
#0 /var/www/html/wp-content/themes/swkoeln/vendor/timber/timber/src/Core.php(68): Timber\Site->meta('home') #1 /var/www/html/wp-content/themes/swkoeln/vendor/twig/twig/src/Extension/CoreExtension.php(1637): Timber\Core->__call('home', Array) #2 /var/www/html/wp-content/themes/swkoeln/vendor/twig/twig/src/Environment.php(361) : eval()'d code(125): twig_get_attribute(Object(Twig\Environment), Object(Twig\Source), Object(StarterSite), 'home', Array, 'any', false, false, false, 17) #3 /var/www/html/wp-content/themes/swkoeln/vendor/twig/twig/src/Template.php(171): __TwigTemplate_59318c560271a4dc2aa74740c399e1bb->block_header(Array, Array) #4 /var/www/html/wp-content/themes/swkoeln/vendor/twig/twig/src/Environment.php(361) : eval()'d code(48): Twig\Template->displayBlock('header', Array, Array) #5 /var/www/html/wp-content/themes/swkoeln/vendor/twig/twig/src/Template.php(394): __TwigTemplate_59318c560271a4dc2aa74740c399e1bb->doDisplay(Array, Array) #6 /var/www/html/wp-content/themes/swkoeln/vendor/twig/twig/src/Template.php(367): Twig\Template->displayWithErrorHandling(Array, Array) #7 /var/www/html/wp-content/themes/swkoeln/vendor/twig/twig/src/Environment.php(361) : eval()'d code(42): Twig\Template->display(Array, Array) #8 /var/www/html/wp-content/themes/swkoeln/vendor/twig/twig/src/Template.php(394): __TwigTemplate_4d0a745a7f7051148cedce069e0b004b->doDisplay(Array, Array) #9 /var/www/html/wp-content/themes/swkoeln/vendor/twig/twig/src/Template.php(367): Twig\Template->displayWithErrorHandling(Array, Array) #10 /var/www/html/wp-content/themes/swkoeln/vendor/twig/twig/src/Template.php(379): Twig\Template->display(Array) #11 /var/www/html/wp-content/themes/swkoeln/vendor/twig/twig/src/TemplateWrapper.php(40): Twig\Template->render(Array, Array) #12 /var/www/html/wp-content/themes/swkoeln/vendor/timber/timber/src/Loader.php(178): Twig\TemplateWrapper->render(Array) #13 /var/www/html/wp-content/themes/swkoeln/vendor/timber/timber/src/Timber.php(1442): Timber\Loader->render('page.twig', Array, false, 'default') #14 /var/www/html/wp-content/themes/swkoeln/vendor/timber/timber/src/Timber.php(1579): Timber\Timber::compile(Array, Array, false, 'default', true) #15 /var/www/html/wp-content/themes/swkoeln/page.php(76): Timber\Timber::render(Array, Array) #16 /var/www/html/wp-includes/template-loader.php(106): include('/var/www/html/w...') #17 /var/www/html/wp-blog-header.php(19): require_once('/var/www/html/w...') #18 /var/www/html/index.php(17): require('/var/www/html/w...')

[Levdbas]

Hey @jrathert , Thank you for trying out Timber 2! Are you calling site.home somewhere in you code? You might want to call site.link here instead. @gchtr , The __call() method in core.php tries to call the meta method on the object. Shouldn't that call option() when we are working with the site object?

[jrathert]

Hi @Levdbas - yes, site.home was used before - replaced it with site.link and everything works like a charm, no more deprecation warnings. Maybe this should be added then to the upgrade guide https://timber.github.io/docs/v2/upgrade-guides/2.0/?! (And/or fixed in the core lib, as you mentioned.)

Thanks for the quick reply, btw.

[Levdbas]

@jrathert , no problem! From what I can see site.home was never a recommended option to link to the homepage. site.link was always the way to go. The way site.home worked was because of this magic __call method that would read the site option home with $site->meta('home') in this case, which would result into the same result. But the meta() method is deprecated on the Site object since 2.0. So I think we have some work to do for this magic __get 'er

[jrathert]

Hi @Levdbas - fair point re: site.home. I actually inherited the theme/project (and needed to learn twig and timber to be able to work with it), and it contained a lot of weird stuff (e.g.: heavy use of post.guid instead of post.link...).

Back to the topic, and also asking @gchtr: Is there anything specifc open re: a 2.0 release? Something to test? To document? Because to me 2.0-rc.1 looks super stable - and I also saw people refering to the 2.0 documentation and running into trouble (the publically available https://timber.github.io/docs/v2/installation/ says installation goes like: composer install timber/timber - which currently installs v1 and lets people get into trouble ;-) ).

[gchtr]

Hey @jrathert , Thank you for trying out Timber 2! Are you calling site.home somewhere in you code? You might want to call site.link here instead. @gchtr , The __call() method in core.php tries to call the meta method on the object. Shouldn't that call option() when we are working with the site object?

In the same as we deprecated calling custom fields directly on posts and other objects, direct access in Timber\Site is deprecated as well.

Instead of calling site.home, you should call site.option('home'). I see that this isn’t very well documented in the Upgrade Guide.

Maybe it would be a good idea to overwrite __call in Timber\Site as well, so that it doesn’t call meta().

Could you create a separate issue for that, @Levdbas?

Back to the topic, and also asking @gchtr: Is there anything specifc open re: a 2.0 release? Something to test? To document? Because to me 2.0-rc.1 looks super stable - and I also saw people refering to the 2.0 documentation and running into trouble (the publically available timber.github.io/docs/v2/installation says installation goes like: composer install timber/timber - which currently installs v1 and lets people get into trouble ;-) ).

If you test it by upgrading your sites to use Timber 2.0, that’s already testing enough. And we’ll see what needs to be documented better when people are using it.

We should definitely fix the documentation about how to install the release candidate. Otherwise, it might really confuse people, especially if they’re not familiar with Composer.

Thanks for mentioning that, @jrathert!

[jrathert]

In the same as we deprecated calling custom fields directly on posts and other objects, direct access in Timber\Site is deprecated as well.

I think the part of the documentation you linked to should is super important for upgrading and should probably be called "Custom fields / meta" instead of just "meta". During my upgrade procedure, I only found out about custom fields handling when reading the ACF part of the docs. I simply did not realize that the section "Meta" is relevant for custom fields in the first place.

[Levdbas]

@gchtr , I've updated the roadmap with some todo's after we release 2.0

[herrschuessler]

In the same as we deprecated calling custom fields directly on posts and other objects, direct access in Timber\Site is deprecated as well.

Is accessing custom fields ddirectly really deprecated or just not the recomended way anymore (as it says in the upgrade guide)? I'm asking because doing to the wrong way doesn't seem to trigger any deprecation warnings.

[gchtr]

In the same as we deprecated calling custom fields directly on posts and other objects, direct access in Timber\Site is deprecated as well.

Is accessing custom fields ddirectly really deprecated or just not the recomended way anymore (as it says in the upgrade guide)? I'm asking because doing to the wrong way doesn't seem to trigger any deprecation warnings.

Okay, maybe this was too long ago since I last looked at this. Let me clarify: We deprecated using {{ timber_object.get_field() }}. Instead, {{ timber_object.meta() }} should be used. We didn’t deprecate direct access to custom fields yet, but it’s not recommended, because it can lead to unexpected effects. The meta() method is the recommendation here as well.

We maybe will deprecate direct access to custom fields in a future major version and eventually remove it. This would need another discussion.

[herrschuessler]

Thanks for the clarification.

[rmens]

Just started the upgrade to Timber 2.0rc1 and it all has been smooth sailing. For an average Wordpress site I’m sure it’s no more than a day of work.

The deprecation warnings are thoughtfully written and the upgrade docs are in pretty good shape. It may have took some time but this is solid work 👏

[gchtr]

Thanks for the feedback, @rmens. That means a lot! 😊

UPDATE: If all goes well, we will have a Timber 2.0 release out by the end of this week.

[gchtr]

Timber 2.0 is released 🚀🎉🌲. Check out the Release notes.

Thanks to everyone who contributed with their time, pull requests, comments and discussions to get us here.

There’s one final todo left on the After release list in this issue. So let’s wait until we fix this before we close this.

[ ] Update readme.md in both branches to refer to eachother.