Undefined Define: IMAGE_EDIT_OVERWRITE

A couple of months ago I was working on a Trac ticket dealing with images and ran into the IMAGE_EDIT_OVERWRITE constant.

I had always assumed it did as it said: when set to true and you edit an image, overwrite the original image instead of creating a new one. But a quick test revealed this was not the case.

I took a quick run over to the Editing wp-config.php page on the WordPress Codex. But IMAGE_EDIT_OVERWRITE was nowhere to be found. In fact, a search of the Codex only uncovered one result: the WordPress 2.9 release notes, when the constant was first introduced. And unfortunately it said very little:

Add ‘IMAGE_EDIT_OVERWRITE’ constant to control edited image save or replace, most useful for setups that have dynamic image resizing

Dang. That’s not very helpful at all.

So I dove head first into the rabbit hole, reviewing the code and testing behaviour in the dashboard.

Default Behaviour

When you edit an image, WordPress’ default behaviour (i.e. IMAGE_EDIT_OVERWRITE is false) is to create a new image and leave the original image alone. Actually it creates a new set of images as it needs to generate all the smaller size images as well.

Let’s say you have the following photo…

photo-1024x683.jpg
photo-150x150.jpg
photo-300x200.jpg
photo.jpg

If you crop it, you would end up with something like this…

photo-1024x683.jpg
photo-150x150.jpg
photo-300x200.jpg
photo-e1430240013837-1024x1024.jpg
photo-e1430240013837-150x150.jpg
photo-e1430240013837-300x300.jpg
photo-e1430240013837.jpg
photo.jpg

If you crop it again, something like this…

photo-1024x683.jpg
photo-150x150.jpg
photo-300x200.jpg
photo-e1430240013837-1024x1024.jpg
photo-e1430240013837-150x150.jpg
photo-e1430240013837-300x300.jpg
photo-e1430240013837.jpg
photo-e1430240387218-150x150.jpg
photo-e1430240387218-150x300.jpg
photo-e1430240387218-512x1024.jpg
photo-e1430240387218.jpg
photo.jpg

Restore Original Image

Each time you edit, it adds a new set of images with a unique appendage.

If you restore the original image, the edits remain on your server. They are not removed. Again, this is the default behaviour, when IMAGE_EDIT_OVERWRITE is false.

Flip the Switch

When you add define( 'IMAGE_EDIT_OVERWRITE', true ); to your wp-config.php the behaviour changes. When you edit an image, it still creates a new image and leaves the original image alone. But when you edit again, it overwrites the first set of images rather than create a new set.

So in our example above, if we had IMAGE_EDIT_OVERWRITE set to true, we would instead end up with the following after the second crop…

photo-1024x683.jpg
photo-150x150.jpg
photo-300x200.jpg
photo-e1430240013837-1024x1024.jpg
photo-e1430240013837-150x150.jpg
photo-e1430240013837-150x300.jpg
photo-e1430240013837-300x300.jpg
photo-e1430240013837-512x1024.jpg
photo-e1430240013837.jpg
photo.jpg

Restore Original Image

As you can see, we just have one set of edited images. You can also see that it overwrote one edited image (i.e. 150×150), created new ones, and ignored others. I expected it to remove the 1024×1024 and 300×300 images, but it didn’t.

If you restore the original image, the set of edited images will be removed. But unfortunately, the images that I expected to be removed earlier are not removed now either…

photo-1024x683.jpg
photo-150x150.jpg
photo-300x200.jpg
photo-e1430240013837-1024x1024.jpg
photo-e1430240013837-300x300.jpg
photo.jpg

I’m guessing that these leftover images are the result of a bug and so I’ve created a new Trac ticket for this. I plan to dig into it on Friday for our monthly company WP Core Contrib Day.

I’ve also added a new Cleanup Image Edits section to the “Editing wp-config.php” page of the WordPress Codex.

I’m a bit perplexed as to why this constant exists at all. It seems like it should be the default behaviour. I think I’ll be turning on IMAGE_EDIT_OVERWRITE on all my sites going forward. I can’t think of a reason why I’d ever want rejected image edits sitting around on my server.

Have you run into this before or is this news to you? Let me know in the comments.

About the Author

Brad Touesnard

As founder of Delicious Brains Inc., Brad wears many hats; from coding and design, to marketing and partnerships. Before starting Delicious Brains, Brad was a busy freelance web developer, specializing in front-end development.

  • Thanks for posting! I always wondered about this when I saw my img folders growing out of control. I will have to experiment with this and see how much it will effect things moving forward.

  • boydbme

    Very useful indeed! Thanks for bringing this previously unknown “feature” to light.

  • Daniel Sturm

    Thanks for this post – never heard of and think I will follow your way.

  • nice, keen to hear the rest of the tail, thanks for the info

  • Great info. This will be very useful for keeping things a little more in control.

  • Great article! Very useful!

  • Thanks for looking into this. I often find myself burrowing down the rabbit hole to figure out things that aren’t documented well. Also, thank you very much for adding what you found to the Codex.

    I doubt the issue you found is the result of a bug; it’s most likely intended behavior. If WordPress actually deleted old versions of your images, you could, potentially, end up with a lot of broken images on your site. If WordPress automatically removed the 1024×1024 version of your image after you restored the original, then anywhere you’re using that 1024×1024 version would now show a broken image instead of an out-of-date image.

    The “Regenerate Thumbnails” plugin works on the same principle. If you change the attributes of any of your registered image sizes and run Regenerate Thumbnails, it purposely does not remove the old versions of your images; it just creates (and overwrites) the ones that are currently registered in your site.

    • Good points. All of that makes sense when IMAGE_EDIT_OVERWRITE is false (the default) but when it’s set to true I think removing the image edits is inline with the rest of the behaviour.

  • Cathy Finn-Derecki

    This is very interesting. It sounds like something that would make sense for smaller sites managed by a single person who knows what s/he is doing. But, with large networks and distributed site management, Curtiss’s point is well taken: Lots of folks would not know what happened to their images, and not get the ramifications of editing their images. In general, I find WP’s image management to be a usability horror show, but, we take what we can to get all the other goodies that come along with it.

  • Thank you. It is help me to save my limited hosting.

  • Wow this is incredibly freaking useful! It makes you wonder why the hell it isn’t better defined in the codex!

  • Brad, have you seen this plugin? https://wordpress.org/plugins/force-regenerate-thumbnails/. It cleans up all the old one’s in uploads folder that have been created over the years.

  • You are correct sir! I’ve noticed the default behavior in the past and thought “what the heck?!” Thanks for getting to the bottom of it for us.

    This sure is a bad default. Some WP hosts that control the defines in wp-config.php are going to want to add this one.

  • aidanlane

    Brad, what about CDN and browser caching? If the “unique appendage” didn’t change, then readers won’t see the updated image until the cache expires, which for our site at least is ‘forever’. If the first edit were to be deleted, wouldn’t it be more sensible to still generate a new “unique appendage”, rather than using the same one? But then again, that could break existing references to the first edit… oh my it becomes messy quickly!

    • Excellent point! I think you’re right. When IMAGE_EDIT_OVERWRITE is set to true, it should create a new unique appendage instead of reusing the old one. You should open up a Trac ticket for this to be looked at and discussed.

  • Nice catch- thanks!!