Improve Image Guide

[gchtr]

Ticket: #429, #404 and #1672

Issue

There have been requests to better document the limitations with Timber’s image functions.

Solution

Let’s try to list the limitations in the image guide.

• Adds new section about the limitations when using a CDN. In TimberImage: Incorrect URL returned when image is stored off-server #429, several people mentioned it doesn’t work with resize(). But then, it wouldn’t work with letterbox(), tojpg() and towebp() either, right? Here’s where I’m not entirely sure.
• Adds changes proposed in TimberImage Resize combined with Retina creates upscaled image, incorrect URL #404 and Remove reference to resize | retina chaining #1672, that are only in the 2.x branch for now. I wanted them to be in the master branch, too.
• Moves the «Using WebP images» section into the «Converting images» section.

Impact

None.

Usage Changes

None.

Considerations

Improving Timber’s overall image experience will eventually make these updates useless. Hopefully.

Testing

None.

[codecov]

Codecov Report

Merging #1925 into master will not change coverage.
The diff coverage is n/a.

@@            Coverage Diff            @@
##             master    #1925   +/-   ##
=========================================
  Coverage     95.04%   95.04%           
  Complexity     1556     1556           
=========================================
  Files            48       48           
  Lines          3672     3672           
=========================================
  Hits           3490     3490           
  Misses          182      182

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 587cff2...ebb67e2. Read the comment docs.

[jarednova]

@gchtr thanks for those adds! I cleaned-up a few details and also tried to elaborate on the CDN limitations. In what I've used before (WPEngine, Pantheon) those filters have all worked 👌. My guess is that plugins/methods that rely on WP "knowing" about the generated images will fail; while ones that are merely watching for new/changed files should work. Any hosts/setups you've found that work for those?

[coveralls]

Coverage remained the same at 94.324% when pulling ebb67e2 on docs/resize-limitations into 587cff2 on master.

[gchtr]

@jarednova Well, I’ve never worked with CDNs and Timber images before, so I really can’t tell 🤷‍♂️. I added some changes to update the text so that it basically says: «It works with some CDN plugins of a certain type, but not with all.»

[jarednova]

Your breakdown of the CDNs is much clearer than mine. I just fixed one other small thing. Good to go!

[palmiak]

@gchtr as I made the same mistake with review as in #1795 (sorry) I want you to consider one more thing:

I would add here a word or two about Pull Zone CDNs. Timber should work flawlessly with all of the them.

There is a nice definition on cdn.net:

When the end-user sends the request for the web content it “pulls” it down from the nearest edge server (cdn location). All the content is cached in one place and the CDN does the work to pull it down into the end-users browser.
The catch: It needs to be said, that the first person to send a request to a new CDN location will find it hasn’t yet pulled that information and cached it ready for viewing. Making their experience seem no different to a site without CDN enabled. But once that first request has been made, the content is cached, and there it will stay until you tell it otherwise.

What do you think about this?

[gchtr]

@palmiak Nevermind about the review misunderstanding :). Thanks, that’s a good hint! Now I too understand the difference between Push and Pull CDN 👍. I updated the text in #1944.