On The Fly Image Processing Causes More Problems Than It Fixes

By Ian McFarlan

Update 2017-03-07: We’re now offering a better solution to on-the-fly image processing.

Images are the bread and butter of the web. Without images and other media the web would be quite different and not nearly as enriching; they are like a rug that really ties the room together. However, there is a concerning trend in the WordPress community to use on the fly (OTF) image processing libraries. Avoidable compatibility issues arise when themes and plugins forego WordPress’ built-in image resizing functionality in favor of OTF processing libraries.

In this article I’ll be going over the implications of OTF processing in WordPress, the benefits of following image standards, and how to get along with images (and subsequently other developers) in a WordPress environment.

What Is On The Fly Image Processing

Before we dive too deep, I should briefly explain what OTF image processing is, how to spot it, and where you can typically find it within WordPress projects. OTF image processing, also known as on-the-fly cropping, enables developers to reshape, crop, and filter images through the use of URL parameters (old school) or manipulation classes (more common approach nowadays). Using OTF processing enables the developer to define one-off, custom dimensions and manipulation of images as they need it.

Many developers use OTF processing due to the ease of use and implementation. Often it is a simple as adding a WordPress plugin, or just a file include, to start making use of OTF processing in any PHP-based CMS. Furthermore, front-end developers can use many OTF libraries because to their simple, concise syntax. Due to this flexibility, developers can keep their toolboxes lean from project to project and have more overlap between design (front-end) and development (backend).

Sounds great? Not in practice.

Two common areas where you can find OTF processing in WordPress are in plugins/themes and custom solutions. It is common for developers of themes and plugins to rely upon a manipulation class like Aqua, VT, TimThumb, or Smart Image Resize (if you’re unsure if a plugin or theme uses OTF processing, have look in it’s source code for classes named Aqua_Resizer, VT, TimThumb, Smart_resize_image etc).

I have also found custom cropping solutions are common in design/advertising agencies that do a lot of client work. Developers are usually pressed for time and look for shortcuts where they can find them – I know I have been guilty of this in years prior.

Maybe That’s Just Your Opinion, Man

By now I imagine many of you are probably asking…

“What’s the big deal‽ I can get my images to output as intended using OTF processing, I don’t need to make use of cumbersome WordPress image sizes, and it’s super quick. Why should I care? Maybe standardized WordPress images are just your opinion, man!”

The Dude: What's the big deal, man?

The answer is as simple as getting along with others.

If all plugins and themes follow the same rules/patterns, compatibility issues are minimal. However, if one plugin deviates it can cause a whole host of problems when interacting with other plugins/themes and WordPress core.

An example of this that comes to mind is when WP Offload S3 is paired with common OTF processing libraries (found in plugins or themes). WP Offload S3 allows you to place your entire media library (and all applicable image sizes) up in S3 and serve it through a CDN. In order to ensure predictable outcomes, we rely heavily upon standardized WordPress conventions for handling images and the media library. We target standardized code like this as accommodating custom solutions is a losing battle.

With WP Offload S3, images cropped OTF are often not uploaded as we have no way to determine details of the images as there is no record of the image in the database (in the form of post or postmeta data). If a OTF processing library does save this information in the database, it is typically saved as postmeta but makes use of custom keys rather than standard attachment metadata. The end result of this ‘no metadata’ scenario can be missing images or images that cannot be offloaded to S3 and can result in images not loading for end users.

A few other big ticket implications of OTF processing…

  • Performance – Each time an image is cropped it loads the OTF processing library. On a page with 100s images this can cause some serious spikes on server resources. Now imagine 1000s of users visiting that page simultaneously.

  • Future Friendliness – WordPress images are getting better with each subsequent release. For example, in v4.7 PDF enhancements are coming to the media library including better previews; how cool is that! Not to mention the many other features being added in this single release. OTF image processing libraries don’t have nearly the same developer resources at their disposal.

  • Security – Many of these libraries are plagued with security issues. File inclusion exploits are common place for a lot of OTF processing libraries and it’s child’s play to take advantage of. TimThumb, for example, has been impacted many times over the years with security exploits resulting in millions of sites having problems.

  • Responsive Images – OTF libraries quickly lose their appeal of immediate implementation when working with responsive images due to the length of code required for every instance where OTF libraries output a different size. WordPress’s core functionality (out of box) includes robust responsive image support.

Let’s learn from the past, and build together with core functionality.

Images Done Right

Thankfully, there are better ways to handle images in WordPress to ensure all plugins can get along together. If you make use of OTF processing libraries today and are worried about refactoring nightmares at this point, try not to worry as WordPress makes it easy to handle images correctly.

Adding Image Sizes

Since v2.9, WordPress has had support for custom image sizes. Over time the image sizes feature has matured and should support most (if not all) custom image size needs within a theme context.

It is very simple to implement a new image size in a functionality plugin or even your functions.php file by making use of the add_image_size function and the after_setup_theme action. Let’s look at a short example…

if ( ! function_exists( 'biglebowski_theme_image_sizes' ) ) {

    function biglebowski_theme_image_sizes() {
        add_image_size( 'feed-cropped-thumb', 300, 150, true );  // cropped, 300 x 150
        add_image_size( 'feed-header', 600 );                    // 600 x unlimited

    add_action( 'after_setup_theme', 'biglebowski_theme_image_sizes' );

With this simple function, we’ve checked for conflicting code, registered two new image sizes, and hooked on to the after_setup_theme action. Because the image sizes are registered within WordPress, we can now make use of filters and actions such as intermediate_image_sizes.

When it is this simple to use built-in WordPress functionality for images, why not use it?

Caveats and Tools

Often when making use of image sizes you will run into instances where you need to resample/regenerate images as you have registered a new image size or modified an existing one. This is where some handy tools can come into play.

Regenerate Thumbnails is a simple and lightweight plugin that allows you to regenerate your images with all active image sizes. This tool is useful for media libraries but can take quite a while to complete on larger libraries.

WP CLI is a command-line interface for WordPress currently maintained by Daniel Bachhuber; a sharp dude you’ll want to follow. You can perform media regenerations via the command-line using the wp media regenerate and they are regenerated to all applicable image sizes. This tool is useful for larger media libraries and in environments where you have command-line access.

It is worth noting that you don’t need to create a plethora of specific image sizes as CSS has matured a great deal since the early 2000s and race for browser standards (Thanks, Mr. Zeldman). Often you can use larger images and slightly resize them in the DOM with traditional CSS. Going forward support for CSS3 features like clip-path and resize are becoming more supported by browsers and could be a good fit for your needs depending on your audience.

Heavy Lifting

I’d argue that 99% of the time, add_image_size can accommodate most developer needs. For those that need powerful image manipulation tools such as Imagick or GD, I’d still strongly suggest making use of core functionality surrounding media and the media library. However, if you do need to step into the land of PHP image libraries, please opt for the WP_Image_Editor class. Since v3.5, this class has abstracted much of the functionality in GD and Imagick, and is a tool for heavier server-side lifting when manipulating images (such as watermarks or color filters).

Let’s look at a brief snippet using WP_Image_Editor safely (to mirror/flip an image) with an existing WordPress attachment already uploaded that has an attachment ID of 42.

// Include if needed
require_once ABSPATH . "wp-includes/class-wp-image-editor.php";

// Base image/attachment
$attachment_id = '42';
$image_path    = get_attached_file( $attachment_id );

// Load the editor
$modified_image = wp_get_image_editor( $image_path );

// Check for any errors when loading WP_Image_Editor
if ( ! is_wp_error( $modified_image ) ) {

    // Flip the image, crank up the quality
    $modified_image->flip( false, true );
    $modified_image->set_quality( 100 );

    // Save image file, update metadata
    $saved_image = $modified_image->save();
    $meta_data   = wp_generate_attachment_metadata( $attachment_id, $saved_image['path'] );

    wp_update_attachment_metadata( $attachment_id, $meta_data );

We’ve loaded up our image and passed it into our WP_Image_Editor class for manipulation. Then we saved the image file and updated the metadata associated with it. This last step, updating metadata, is quite important if you are modifying image dimensions, the filesize of the image, etc. When updating metadata of an attachment you are saving important information to the database allowing others (and yourself) to access and further work with the attachment. This includes proper deletion of images. Having the relevant metadata of an image will allow you to ensure all resized images are removed when an image is deleted from the media library and no orphan image sizes are left behind.

If you are uploading a whole new image (either through WordPress or an external source like an API), you can still make use of the WP_Image_Editor class for any trickier image manipulation. You’ll want to be sure to latch onto media_handle_upload for the initial upload as it handles much of the upload process (file saving, metadata extraction, etc.) in a single function.

In the rare case that you need even more power there is hope; you can extend the WP_Image_Editor class! This is not for the faint of heart and can quickly get off the rails of standardization. But, if you extend the base class responsibly and always make use of the media library, you should be able to add more options and methods to WP_Image_Editor. For examples of this, take a look at the WP_Image_Editor_Imagick and WP_Image_Editor_GD classes. They extend the base editor class to work specifically for the two respective PHP image libraries and are very well commented.

Early in development, if you approach your image needs (especially those that require heavier lifting) with compatibility in mind you’ll be on the right path to playing well with other plugins, themes and WordPress core.

Where From Here?

WordPress core is always being updated and with it comes stability, security and new features. The additions in 4.7 alone are significant to extending the media library further and this is a single release.

Furthermore, say you find a shortcoming in how WordPress handles images. The true beauty of WordPress is that it’s open source. You can discuss a new feature with the WordPress community by submitting a Trac ticket, chatting on WordPress Core Slack, or writing a blog post about the feature. If you find a bug you have the power to report it and/or patch it yourself.

Let’s finally rid the WordPress community of OTF image processing libraries and instead rely upon core functionality. Compatibility with other developer’s code (whether a theme or plugin) should be easy if we all work from the same set of rules.

About the Author

Ian McFarlan

Ian is a former member of the Delicious Brains team. He is a PHP and WordPress developer in Ontario, Canada. Coming from an advertising background, he loves to create powerful, easy to use tools. He has a bit of an addiction to learning.