The “-scaled” suffix for images, or what WP does with large images
Since WordPress 5.3, when uploading very large images, a smaller copy is created so that when requesting the full
size, this copy of the image is used instead of the original. By default, a "decent" size is considered to be an image no larger than 2560 pixels in width or height.
More details on how it works.
Suppose we upload an image with the size of 5000x2000px. In this case, WordPress, in addition to creating other thumbnails, will create a copy of this image with the size of 2560x1024px (proportionally fit it into the 2560 size) and save it in the uploads folder with a new name {IMAGE_NAME}-scaled.{EXT}
. Then, it will replace the path of the original image in the metadata with this created path, so that this copy is considered the original. It will also save the name of the original image in the metadata under the key original_image
, see _wp_image_meta_replace_original().
The created copy of the original with a "decent" size is now considered the original image, and the path to it is written in the meta-field _wp_attached_file
. Now the function that usually returns the original path get_attached_file() or the original URL wp_get_attachment_url() and other functions that should return the original image will return the new "-scaled" path/URL.
The "-scaled" size is NOT created for .png images because there are cases where the reduced size weighs more than the original, see ticket #48736.
The original image file is not deleted and is located in the uploads folder, and the path or URL to it can be obtained through the new functions for WP 5.3:
A reduced version will be created for any image whose width or height exceeds the specified threshold - 2560
px.
The threshold (the "decent" size referred to) can be changed using the big_image_size_threshold filter, returning the desired size:
# Change the `-scaled` size (maximum allowable size) of the image by width/height add_filter( 'big_image_size_threshold', function( $size, $imagesize, $file, $attachment_id ){ return 1600; }, 10, 4 );
Or you can completely disable all this "-scaled" logic by returning 0 in the filter:
# Disable the `-scaled` size - limit the maximum size of the image add_filter( 'big_image_size_threshold', '__return_zero' );
How to delete the original image after it has been uploaded if a -scaled
size has been created
When an image is uploaded, if it is of a large size, WordPress saves both the original image and a reduced copy with the "-scaled" suffix. How to save only the "-scaled" version without saving the original image?
// Removes original image file from disk if `-scaled` size has been created. Works for WP 5.3+ only. add_filter( 'wp_generate_attachment_metadata', 'remove_scaled_original_image_file', 10, 3 ); /** * Removes original image file from disk if `-scaled` size has been created. * * Function for hook `wp_generate_attachment_metadata`. * * @param array $image_meta * @param int $attachment_id * @param string $context Exists from WP 5.3+. * * @return array */ function remove_scaled_original_image_file( $image_meta, $attachment_id, $context = '' ){ if( $context !== 'create' || empty( $image_meta['original_image'] ) ){ return $image_meta; } // remove original image file from disk $image_file = get_attached_file( $attachment_id ); $original_file = path_join( dirname( $image_file ), $image_meta['original_image'] ); $removed = unlink( $original_file ); if( $removed ){ unset( $image_meta['original_image'] ); } else { trigger_error( 'Couldn`t remove original_image file.' ); } return $image_meta; }
--