Introducing WP Image Processing Queue - On‑the‑Fly Image Processing Done Right

I’ve been bugging core contributors and plugin authors about background processing for a year and half now. To the point where Krogsgard even made fun of me for it at the WordCamp EU after party. “There goes Brad, talking about background processing again.” He was joking, but it’s true. Clearly I think it’s an important subject, but I was surprised to realize that I haven’t talked about it at all on this blog.

Ash wrote about background processing just over a year ago. He presented an awesome library that he coded for WP Offload S3 and released it as a standalone library on GitHub for others to use. I wasn’t the only one who was impressed. WooCommerce and Ninja Forms are using it as well.

The library is great, but I realized there was a problem. If each theme/plugin implements their own background processing queue instead of sharing one queue, we could end up running a bunch of jobs at the same time and impacting server performance. As more and more themes/plugins start to do their own background processing (whether they use this library or do their own thing), the bigger this problem is going to get.

I think the best solution is to get background processing into WordPress core so that all themes/plugins can share a single queue and ensure we don’t impact server performance. And so started my crusade.

At PressNomics, I had a great chat with Mike Schroder. He presented a very good path to core: find a feature that WordPress core needs and that needs background processing. In other words, piggyback! This is exactly how the image optimization stuff made it into core last year: by piggybacking off of responsive images. For background processing, he proposed coming up with an alternative to on-the-fly image processing (OTFIP). Whoa, turns out OTFIP is a problem we regularly deal with for WP Offload S3 as well. This could be a “two birds – one stone” kind of thing. Stars were aligning.

On-the-Fly Image Processing (OTFIP)

We wrote about OTFIP just a few months ago and explained that it tends to cause more problems than it solves. To recap, the main problem OTFIP solves is to cut down on generating (and storing) images that will never be used. If each theme/plugin uses add_image_size() to generate the image sizes they need, the number of image sizes quickly balloons.

Don’t believe me? We have a little competition going on between team members to spot the WordPress install with the most registered image sizes. So far Ash is winning with 49!

To be clear, WordPress generates 49 images of various sizes when an image is uploaded to that WordPress install. That’s easily a minute of waiting for image generation to complete. I’m going to go out on a limb and guess that a solid 29 of those generated images will never be used and yet, they’re taking up hard drive space. This is an extreme example, but we commonly see WordPress installs with 20 or so registered image sizes.

OTFIP FTW

To solve this problem, some developers include OTFIP libraries in their themes/plugins and generate images of the exact size they need when they need it. For example, if you used the popular Aqua Resizer library you might call the following function in your theme/plugin:

<?php $resized_image_url = aq_resize( $image_url, $width, $height, $crop ); ?>

If the resized image doesn’t exist yet, it would be generated and saved alongside the original in the filesystem. This sounds great, but the page load time suffers greatly because it has to wait for the image to be generated before loading the page. And if a page has a bunch of these calls (e.g. one for every blog post on an archive page) it can be a ridiculously long wait and possibly even time out. Plus, image resizing is a CPU and memory intensive operation. So what happens to the server when several of these pages are loaded at the same time? Oops.

Finally, guess what happens when the original image is removed from the Media Library. Yep, the resized image is left behind because WordPress core doesn’t know about it. Plus WordPress core can’t add the resized images to the srcset so no responsive images.

What we need is a solution that doesn’t affect page load time, is mindful of server resources, and works seamlessly with WordPress core as it is today.

Image Processing Queue is Born

At WordCamp US Contributor Day this past December, I decided to try hack together an image processing library that would have all of the benefits of OTFIP but with none of the negatives. And voilà, after a few hours Image Processing Queue was born.

Using it is pretty straightforward. You simply include a file to load Image Processing Queue and its dependencies:

require_once TEMPLATEPATH . '/image-processing-queue/image-processing-queue.php';

Then you can call the ipq_get_theme_image() function in your theme/plugin templates to output an image:

echo ipq_get_theme_image( $post_id, array(
        array( 600, 600, false ),
        array( 1280, 1280, false ),
        array( 1600, 1600, false ),
    ),
    array(
        'class' => 'header-banner'
    )
);

If all the images have already been generated, the output would look something like this:

<img class="alignnone size-full wp-image-22495 header-banner"
width="4096" height="3072" src="https://domain.com/wp-content/uploads/2017/03/image.jpg" 
srcset="https://domain.com/wp-content/uploads/2017/03/image-600x450.jpg 600w,
https://domain.com/wp-content/uploads/2017/03/image-1280x960.jpg 1280w,
https://domain.com/wp-content/uploads/2017/03/image-1600x1200.jpg 1600w,
https://domain.com/wp-content/uploads/2017/03/image-300x225.jpg 300w,
https://domain.com/wp-content/uploads/2017/03/image-1024x768.jpg 1024w"
sizes="(max-width: 720px) 100vw, 720px">

If an image hasn’t been generated yet, it is left out and queued to be generated in the background. So if it’s the first time running the above function call, you might end up with this output:

<img class="alignnone size-full wp-image-22495 header-banner"
width="4096" height="3072" src="https://domain.com/wp-content/uploads/2017/03/image.jpg" 
srcset="https://domain.com/wp-content/uploads/2017/03/image-300x225.jpg 300w,
https://domain.com/wp-content/uploads/2017/03/image-1024x768.jpg 1024w"
sizes="(max-width: 720px) 100vw, 720px">

Regardless of whether the images exist or not, we load the page right away and relegate image generation to the background. No holding up the page load for generating images.

Also, when a new image size is generated, we add metadata to the attachment so that WordPress core understands that the resized image exists. This allows WordPress core to automatically add the generated image sizes to the srcset when generating the image tag. It also allows WordPress core to delete the generated images when the original image is removed from the Media Library. The meta data is in the exact same format as the meta data added for image sizes registered with add_image_size(). Any themes/plugins that use the image size metadata can also use it and therefore use the generated image sizes.

Next Stop, WordPress Core

I would love to see this rolled into WordPress core along with the background processing library. It would make images much easier to manage for WordPress theme/plugin developers and would hopefully result in the abandonment of OTFIP libraries altogether. I’m not sure how something like this would fit into WordPress core’s new release cycles, but I am sure I will continue bugging people about it.

If you’re a theme/plugin author, please consider using Image Processing Queue instead of an OTFIP library next time. You get all the benefits without any of the negatives. And the more this library is used, the easier the case can be made for rolling it into WordPress core.

Of course there is still lots of room for improvement here. Ash is currently working on the background processing library, adding the ability to disable the HTTP worker and spawn multiple queue workers via the CLI. This is great for people with full control of their servers who want more dependable workers. He’s also rebuilding the queue backend, saving jobs to the database by default, but allowing you to swap in any queue backend. For example, you could use Redis to store your jobs.

If you find a bug in either Image Processing Queue or WP Background Processing, please open an issue (or a pull request) on the appropriate GitHub repo.

Have you used OTFIP libraries? Would you give Image Processing Queue a shot instead? What about background processing? What would you like to see happen there? Let us know in the comments.

Update 2017-03-08: I’ve added this library as a plugin on WordPress.org.

This entry was posted in WP Offload Media, Workflow and tagged WordPress, Development, WordPress Development Tips, Background Processing, Image Processing.

.replybox-fallback, .replybox-fallback ul { list-style: none; }

Marc says:

March 7, 2017 at 12:16 pm

This sounds great – we try to be a bit more judicious about what sizes we include but we recently took over a client site with exactly this issue. https://uploads.disquscdn.com/images/370946639e9538d0c1ac15c3d698f4a8ee055c217de24958e8ed48bcc274a8fa.png Compiling these into a srcset is a lovely touch too.

speed photos instagram says:

September 27, 2017 at 7:19 pm

I agree with you…

Reply
printable january calendar says:

December 2, 2017 at 5:41 pm

looks good.

Reply

Georg says:

March 7, 2017 at 12:19 pm

Thanks for sharing this, sounds great! How does this work together with WP Offload S3? Are generated images automatically transferred to S3 aswell? Best, Georg

Ashley says:

March 7, 2017 at 12:37 pm

Yup, WP Offload S3 will automatically upload the generated images to S3.

Reply
- Gregg says:
  
  March 7, 2017 at 1:04 pm
  
  Considering the S3 outage last week do you still stand behind it’s value? I would love to see a S3 implementation that offered a host server fallback similar to how many implement Google served libraries… I use the EWWW Image Optimizer Cloud and Imsanity and am very happy with the results. I also always turn off Worpdress image resizing because of the structure that is outlined above in my opinion is not a good solution. Imsanity prevents overly large images and EWWW optimizes uploaded images well. Very interesting post though!
  
  Reply
- Georg says:
  
  March 17, 2017 at 2:04 pm
  
  Ashley, I am interested how is this done that WP Offload S3 gets to know about those additional sizes? Is this stored somewhere in the Database? Edit: Question answered: "Images generated by Image Processing Queue are added to the post meta."
  
  Reply

Darjan Panic says:

March 7, 2017 at 12:25 pm

Now we just need to piggyback a solid image compression in there 🙂 Or will WP Offload handle that in the future? 😉

Brad says:

March 7, 2017 at 3:54 pm

You can hook up EWWW right now and it will work with WP Offload S3. We don’t have any plans to offer image optimization services.

Reply
- Nico Prat says:
  
  October 3, 2017 at 11:03 am
  
  Could you elaborate a bit on this? Didn’t find anything about Ewww. Is there anything special to be done, or any image generated by your plugin will be compressed (as far as they’re in the /uploads folder)? Thanks.
  
  Reply
  - Brad says:
    
    October 6, 2017 at 9:11 am
    
    WP Offload S3 contains code that makes it compatible with EWWW as per our documentation and EWWW’s site.
    
    Reply

Matt Mullenweg says:

March 7, 2017 at 1:38 pm

Definitely not a fit for core this year. Would be good to get as a plugin on the directory (instead of just Github) so we can see if it’s useful to more people.

zmonteca says:

March 7, 2017 at 1:44 pm

Dang. Shot that down pretty quickly. Cool to see you’re still intimately involved in WP-Core. I would have never imagined. I guess once a dev, always a dev.

Reply
Brad says:

March 7, 2017 at 4:36 pm

Good call, done: https://wordpress.org/plugins/image-processing-queue/

Reply
- David says:
  
  December 23, 2019 at 4:59 pm
  
  Not sure that putting it in the plugin directory will prove (has proven) whether this is useful to more people. Unless I’m wrong, we still need to integrate this into our theme for it to work. People who are capable of doing that are probably also capable of integrating this library directly. People who aren’t will install it, see it does nothing, and uninstall it. I think the case for including it in core is very strong. Save the planet!
  
  Reply
speed photos instagram says:

September 27, 2017 at 7:19 pm

good point !

Reply
printable calendar 2017 says:

October 27, 2017 at 1:23 am

team members to spot the WordPress install with the most registered image sizes. So far Ash is winning with 49!

Reply
printable january calendar says:

December 2, 2017 at 5:41 pm

I agree with you.

Reply
Terence Milbourn says:

March 18, 2019 at 9:39 am

Instead of acting as a roadblock, you should be championing efforts like this which have the potential to stop the image bloat that has kept WordPress stuck in an image-handling time-warp, for as long as I have known it. Sometimes I wonder which planet you live on. Obviously one which has endless disk space, unlimited bandwidth and no comprehension of the downside of wasting resources. And your lack of awareness to the community as a whole is breath-taking. Just stop for a minute and imagine the amount of disk-space, electricity and other resources 30% of the Web is now wasting due to your tardiness in grasping this as a serious issue, which should be resolved immediately, not when you get round to it. I wonder how the money-men would react if this waste of the Web’s resources was quantified, and the community started a campaign aimed at getting WordPress to accept its responsibility? Is that what we have to do to get you to take this seriously and do something about it?

Reply
Joost de Valk says:

September 19, 2022 at 2:59 am

Hi Matt, Care to elaborate on why this isn’t a good fit? This seems like a very easy performance win, and you shoot it down on sight, I don’t really get why you’d do that.

Reply

Lu says:

March 7, 2017 at 2:28 pm

This looks really good – support for multiple sizes is definitely less hackish than Aqua Resizer which I absolutely love, most of all for its good handling of on the fly cropping.

jyaz says:

March 7, 2017 at 2:42 pm

How do you guys handle storage of media library assets? It would be awesome if the Media Library could just be stored on S3 and not mirrored locally, but if the images are not local, it’s not possible to use the WP cropping tool (which is so confusing, I don’t understand how people use it, but many do).

Brad says:

March 7, 2017 at 4:38 pm

Our WP Offload S3 plugin does exactly what you’re describing, allows you to remove local files, and works with cropping. Magic. 🙂

Reply
- Ara Garabedian says:
  
  March 8, 2017 at 12:04 am
  
  Brad, does WP Offload S3 also crop around a focal point defined in an image? This is (IMHO) a sorely overlooked feature of a lot of image services. Examples: http://www.wpsmartcrop.com/how-does-it-work/ https://en-au.wordpress.org/plugins/acf-focal-point/
  
  Reply

wkingio says:

March 7, 2017 at 3:21 pm

How do you set the sizes attribute?

Dustin says:

March 7, 2017 at 8:31 pm

So how do we find out how many images are being generated then.

Dale Reardon says:

March 8, 2017 at 12:08 am

I am just so impressed with you as a developer. You worry about server load, caching, code efficiency, execution time etc, all of which many plugin developers seem to know nothing about, not care about, or don’t know how to do. If you or anyone else knows of a developer as good as you, that wants to join us in developing a BuddyPress / BBPress community for the disability sector, either as an equity partner, employee with profit share etc, then please get in touch: https://mydisabilitymatters.club

Ralf Koller says:

March 8, 2017 at 6:06 am

How about extending the plugin with the concept of image sets to deal with the generation of unnecessary versions of an image. I’ve suggested that over at the Responsive Image plugin about two years ago ( https://github.com/ResponsiveImagesCG/wp-tevko-responsive-images/issues/45 ). If you like the general idea I might update and reshape the proposal and file an issue over at the Image Processing Queue repo on Github.

Sallie Goetsch says:

March 8, 2017 at 6:15 pm

Just to be sure I understand the way this is supposed to work: if I install the plugin or include the library, I would then NOT define custom image sizes in functions.php, but rather replace any get_post_thumbnail() or other image calls with ipq_get_theme_image()? Or is this just for things like header image where you aren’t going to use the image size somewhere else? (I’m thinking of cases where a certain post type has a particular size for its featured images that it would make no sense to generate for other post types.)

Brad says:

March 8, 2017 at 9:27 pm

I would then NOT define custom image sizes in functions.php, but rather replace any get_post_thumbnail() or other image calls with ipq_get_theme_image()? Yep, you got it.

Reply
- Sallie Goetsch says:
  
  March 8, 2017 at 10:06 pm
  
  Oh, very nice. I hate the way the uploads folder gets cluttered with images at sizes that aren’t used. Someone please tell the creators of Co-Authors Plus to incorporate it in that plugin, which is responsible for creating 5 extra sizes of EVERY image when it should only apply to author avatars.
  
  Reply

Patrick W says:

March 9, 2017 at 9:21 am

I’ve been struggling with the number of image sizes generated for years, this is a near perfect solution for me. Thanks so much for developing and releasing this! I hope it makes it into core soon. I was wondering if you would mind helping with my specific use case. I use the ACF addon, Image Crop Tool and I have specified a fixed image size an image should be cropped to, so in my case, it would be great if the original image size was included into the srcset array. I’ve tried manually specifying the original image width and height inside the ipq_get_theme_image function call, but this doesn’t work. I’m guessing it sees that a crop of this size already exists and stops there. How could I make ipq_get_theme_image return the original full image in its srcset list? Also, does it matter that the srcset images are not in width order? I thought it was supposed to be smallest width first, then larger. I believe that the browser matches the first valid match but I could be wrong… http://stackoverflow.com/questions/39644823/picture-element-srcset-order-importance

Brad says:

March 9, 2017 at 9:45 am

The srcset stuff is handled by WordPress core. We just pop the metadata into the database that it needs to generate the srcset. If I remember right, I believe there was a good reason the WP Core developers didn’t include the original image in the srcset. I can’t remember exactly what it was. You might be able to find the answer browsing through old posts at https://make.wordpress.org/core/. There may also be a filter to some kind of mechanism to enable WP to add the originals to the srcset.

Reply
- Patrick W says:
  
  March 9, 2017 at 11:00 am
  
  Thanks, I’ll try and figure it out. I run wp_get_attachment_image_srcset, imageID, ‘full’ it returns the full srcset I need, including the new crops generated by wp-image-processing-queue.
  
  Reply
  - Patrick W says:
    
    March 10, 2017 at 5:44 am
    
    I had to modify class-image-processing-queue.php in the end, (just in case it helps anyone else, I added ‘full’ to the return wp_get_attachment_image call inside get_image) as I couldn’t find a filter. It works really well now, cheers! The order of the images in srcset doesn’t seem to matter either, when I tested this about a year ago I remember it mattering. A nice future addition would be somehow utilising this http://www.responsivebreakpoints.com/ calculation in the ipq_get_theme_image $sizes array. E.g. if the image is above 3000px, have more thumbnails available.
    
    Reply

Matilde says:

April 20, 2017 at 3:00 pm

This is awesome. Thank you for sharing!

cre8ddesign says:

October 6, 2017 at 12:00 am

"You get all the benefits without any of the negatives." I’ve seen this type of approach suggested before, but surely a major negative is the fact the first visitor(s) to your site will see a completely wrong image. The majority of times lots of image sizes like this are required are due to them needing to be cropped to exact sizes to fit a certain layout (as opposed to simply scaling, where large numbers of different sizes aren’t really required). Sure, it will only affect a small number of visitors to your site – but that’s also true for the case where they have to wait for the image to be cropped before the site displays. I’d rather wait and see the correct results, than not wait and see something broken (or potentially highly unoptimised).

Brad says:

October 6, 2017 at 9:04 am

A workaround of that problem would be to add a new cropped image size to the list of images sizes generated at upload time. Then there would be a cropped version available even if it isn’t the exact size the theme wants.

Reply
- cre8ddesign says:
  
  October 6, 2017 at 4:29 pm
  
  I can’t see how that would help; themes crop images to specific sizes because they need images at exactly that size. Having an image cropped to a different size would result in an equally broken look.
  
  Reply
  - Brad says:
    
    October 7, 2017 at 7:56 pm
    
    Why would it be broken?
    
    Reply
    - cre8ddesign says:
      
      October 8, 2017 at 8:52 pm
      
      I’m struggling to think of an example where it wouldn’t be 🙂 Say, a grid layout where you wanted images to be cropped to ensure everything lines up. Or a banner where exact dimensions are important due to responsiveness / scrolling effects. Take your Disqus profile picture and imagine you’ve uploaded a tall image that hadn’t been cropped to a square. Sure, you could add CSS to provide a fallback mechanism by scaling images to max dimensions, putting them in fixed size boxes with overflow hidden, etc. But if the theme specifically asked for a cropped image, the end result is that you will always be seeing the wrong result.
    - Brad says:
      
      October 9, 2017 at 2:39 pm
      
      Last time I checked, wp_get_attachment_image() respects the aspect ratio of the image size you specify. That is, if you specify a square image, it will only put image sizes that are square into the srcset. So if you generate some larger square images at upload time (in addition to WP’s default square image), it shouldn’t appear broken.
    - cre8ddesign says:
      
      October 9, 2017 at 4:29 pm
      
      Right, sorry, we’re talking about different things. So you’re saying every time you want an image cropped to a new proportion, you have no option but to go back to the original method of generating them for every image – which means this plugin no longer achieves its purpose. I guess it cuts down on the number of images if you have a huge set of equal proportions, but the most common use-case for me for on-the-fly image processing is, say, a special widget which displays feature images of posts, where it’s unnecessary to create the special cropped size for every image uploaded to WordPress.

Уроки WordPress says:

October 24, 2018 at 3:08 pm

Can we do auto height or auto width? Proportional resize imabe by one side.

Dale Reardon says:

March 18, 2019 at 8:07 pm

i, Performance is such an important issue that core is just not paying enough attention to, so in the meantime we have to look after ourselves. A query – I use several of your plugins Offload Media and now Offload SES – do you share the queue between your own plugins at least? Also running WooCommerce so there is another queue! Dale.

Brad says:

March 21, 2019 at 7:23 am

Unfortunately no. It’s still the wild west until WP core implements a queue that all plugins and themes can use. A step further than that even would be if multiple installs of WordPress running on a single server could share a single queue and be mindful of server resource usage.

Reply

Null Email says:

December 3, 2022 at 3:19 am

We’re in 2022 and every now and then I visit this article to see if something new posted….. could you please release an update for this?