* The class to operate media data.
defined( 'WPINC' ) || exit();
* Handles media-related optimizations like lazy loading, next-gen image replacement, and admin UI.
class Media extends Root {
const LIB_FILE_IMG_LAZYLOAD = 'assets/js/lazyload.min.js';
const TYPE_BATCH_RESCALE_ORI = 'batch_rescale_ori';
* Current page buffer content.
* WordPress uploads directory info.
* List of VPI (viewport images) to preload in <head>.
private $_vpi_preload_list = [];
* The user-level next-gen format supported (''|webp|avif).
* The system-level chosen next-gen format (webp|avif).
private $_sys_format = '';
public function __construct() {
$this->_wp_upload_dir = wp_upload_dir();
if ( $this->conf( Base::O_IMG_OPTM_WEBP ) ) {
$this->_sys_format = 'webp';
if ( 2 === $this->conf( Base::O_IMG_OPTM_WEBP ) ) {
$this->_sys_format = 'avif';
if ( ! $this->_browser_support_next_gen() ) {
$this->_format = apply_filters( 'litespeed_next_gen_format', $this->_format );
* @since 7.4 Add media replace original with scaled.
public function after_user_init() {
// Hook to attachment delete action (PR#844, Issue#841) for AJAX del compatibility.
add_action( 'delete_attachment', [ $this, 'delete_attachment' ], 11, 2 );
// For big images, allow to replace original with scaled image.
if ( $this->conf( Base::O_MEDIA_AUTO_RESCALE_ORI ) ) {
// Added priority 9 to happen before other functions added.
add_filter( 'wp_update_attachment_metadata', [ $this, 'rescale_ori' ], 9, 2 );
// Due to ajax call doesn't send correct accept header, have to limit webp to HTML only.
if ( $this->webp_support() ) {
if ( function_exists( 'wp_calculate_image_srcset' ) ) {
add_filter( 'wp_calculate_image_srcset', [ $this, 'webp_srcset' ], 988 );
// add_filter( 'wp_get_attachment_image_src', [ $this, 'webp_attach_img_src' ], 988 );// todo: need to check why not
// add_filter( 'wp_get_attachment_url', [ $this, 'webp_url' ], 988 ); // disabled to avoid wp-admin display
if ( $this->conf( Base::O_MEDIA_LAZY ) && ! $this->cls( 'Metabox' )->setting( 'litespeed_no_image_lazy' ) ) {
self::debug( 'Suppress default WP lazyload' );
add_filter( 'wp_lazy_loading_enabled', '__return_false' );
add_filter( 'litespeed_buffer_finalize', [ $this, 'finalize' ], 4 );
add_filter( 'litespeed_optm_html_head', [ $this, 'finalize_head' ] );
* Handle attachment create (rescale original).
* @param array $metadata Current meta array.
* @param int $attachment_id Attachment ID.
* @return array Modified metadata.
public function rescale_ori( $metadata, $attachment_id ) {
// Test if create and image was resized.
if ( $metadata && isset( $metadata['original_image'], $metadata['file'] ) && false !== strpos( $metadata['file'], '-scaled' ) ) {
// Get rescaled file name.
$path_exploded = explode( '/', strrev( $metadata['file'] ), 2 );
$rescaled_file_name = strrev( $path_exploded[0] );
// Create paths for images: resized and original.
$base_path = $this->_wp_upload_dir['basedir'] . $this->_wp_upload_dir['subdir'] . '/';
$rescaled_path = $base_path . $rescaled_file_name;
$new_path = $base_path . $metadata['original_image'];
// Change array file key.
$metadata['file'] = $this->_wp_upload_dir['subdir'] . '/' . $metadata['original_image'];
if ( 0 === strpos( $metadata['file'], '/' ) ) {
$metadata['file'] = substr( $metadata['file'], 1 );
// Delete array "original_image" key.
unset( $metadata['original_image'] );
if ( file_exists( $rescaled_path ) && file_exists( $new_path ) ) {
// Move rescaled to original using WP_Filesystem.
if ( ! $wp_filesystem ) {
require_once ABSPATH . '/wp-admin/includes/file.php';
$wp_filesystem->move( $rescaled_path, $new_path, true );
// Update meta "_wp_attached_file".
update_post_meta( $attachment_id, '_wp_attached_file', $metadata['file'] );
public function handler() {
$type = Router::verify_type();
case self::TYPE_BATCH_RESCALE_ORI:
$this->_batch_rescale_ori();
* Batch replace all scaled images with their originals.
* Follows the rm_bkup() pagination pattern.
private function _batch_rescale_ori() {
// phpcs:ignore WordPress.Security.NonceVerification.Recommended
$offset = ! empty( $_GET['litespeed_i'] ) ? absint( wp_unslash( $_GET['litespeed_i'] ) ) : 0;
$img_q = "SELECT a.ID, b.meta_value
LEFT JOIN `$wpdb->postmeta` b ON b.post_id = a.ID
WHERE b.meta_key = '_wp_attachment_metadata'
AND a.post_type = 'attachment'
AND a.post_status = 'inherit'
AND a.post_mime_type IN ('image/jpeg', 'image/png', 'image/gif')
// phpcs:ignore WordPress.DB.DirectDatabaseQuery, WordPress.DB.PreparedSQL.NotPrepared
$list = $wpdb->get_results( $wpdb->prepare( $img_q, [ $offset * $limit, $limit ] ) );
foreach ( $list as $v ) {
if ( ! $v->ID || ! $v->meta_value ) {
// phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged
$meta_value = @maybe_unserialize( $v->meta_value );
if ( ! is_array( $meta_value ) ) {
if ( empty( $meta_value['original_image'] ) || empty( $meta_value['file'] ) || false === strpos( $meta_value['file'], '-scaled' ) ) {
// Extract subdirectory from metadata file path (e.g. "2024/05/photo-scaled.jpg" → "2024/05").
$subdir = pathinfo( $meta_value['file'], PATHINFO_DIRNAME );
// Build relative paths for rename().
$scaled_filename = basename( $meta_value['file'] );
$scaled_path = $subdir . '/' . $scaled_filename;
$original_path = $subdir . '/' . $meta_value['original_image'];
// Verify scaled file exists before proceeding
// TODO: need to ues isfile func to allow hook from offload plugins
$basedir = $this->_wp_upload_dir['basedir'] . '/';
if ( ! file_exists( $basedir . $scaled_path ) ) {
self::debug( 'Skipped: scaled file missing [pid] ' . $attachment_id );
// Move scaled file → original file using WP_Filesystem via rename().
$this->rename( $scaled_path, $original_path, $attachment_id );
// Update metadata: point file to original, remove original_image key.
$meta_value['file'] = $subdir . '/' . $meta_value['original_image'];
unset( $meta_value['original_image'] );
wp_update_attachment_metadata( $attachment_id, $meta_value );
update_post_meta( $attachment_id, '_wp_attached_file', $meta_value['file'] );
self::debug( 'batch_rescale_ori offset=' . $offset . ' processed=' . $count );
// Check if there are more rows to process.
// phpcs:ignore WordPress.DB.DirectDatabaseQuery, WordPress.DB.PreparedSQL.NotPrepared
$to_be_continued = $wpdb->get_row( $wpdb->prepare( $img_q, [ $offset * $limit, 1 ] ) );
if ( $to_be_continued ) {
return Router::self_redirect( Router::ACTION_MEDIA, self::TYPE_BATCH_RESCALE_ORI );
Admin_Display::success( sprintf( __( 'Batch rescale completed.', 'litespeed-cache' ) ) );
* Add featured image and VPI preloads to head.
* @param string $content Current head HTML.
* @return string Modified head HTML.
public function finalize_head( $content ) {
// <link rel="preload" as="image" href="xx">
if ( $this->_vpi_preload_list ) {
foreach ( $this->_vpi_preload_list as $v ) {
$content .= '<link rel="preload" as="image" href="' . esc_url( Str::trim_quotes( $v ) ) . '">';
* Adjust WP default JPG quality.
* @param int $quality Current quality.
* @return int Adjusted quality.
public function adjust_jpg_quality( $quality ) {
$v = $this->conf( Base::O_IMG_OPTM_JPG_QUALITY );
public function after_admin_init() {
add_filter( 'jpeg_quality', [ $this, 'adjust_jpg_quality' ] );
add_filter( 'manage_media_columns', [ $this, 'media_row_title' ] );
add_filter( 'manage_media_custom_column', [ $this, 'media_row_actions' ], 10, 2 );
add_action( 'litespeed_media_row', [ $this, 'media_row_con' ] );
* Media delete action hook.
* @param int $post_id Post ID.
public static function delete_attachment( $post_id ) {
self::debug( 'delete_attachment [pid] ' . $post_id );
Img_Optm::cls()->reset_row( $post_id );
* Return media file info if exists.
* This is for remote attachment plugins.
* @param string $short_file_path Relative file path under uploads.
* @param int $post_id Post ID.
* @return array|false Array( url, md5, size ) or false.
public function info( $short_file_path, $post_id ) {
$short_file_path = wp_normalize_path( $short_file_path );
$basedir = $this->_wp_upload_dir['basedir'] . '/';
if ( 0 === strpos( $short_file_path, $basedir ) ) {
$short_file_path = substr( $short_file_path, strlen( $basedir ) );
$real_file = $basedir . $short_file_path;
if ( file_exists( $real_file ) ) {
'url' => $this->_wp_upload_dir['baseurl'] . '/' . $short_file_path,
'md5' => md5_file( $real_file ),
'size' => filesize( $real_file ),
* WP Stateless compatibility #143 https://github.com/litespeedtech/lscache_wp/issues/143
* Should return array( 'url', 'md5', 'size' ).
$info = apply_filters( 'litespeed_media_info', [], $short_file_path, $post_id );
if ( ! empty( $info['url'] ) && ! empty( $info['md5'] ) && ! empty( $info['size'] ) ) {
* @param string $short_file_path Relative file path under uploads.
* @param int $post_id Post ID.
public function del( $short_file_path, $post_id ) {
$real_file = $this->_wp_upload_dir['basedir'] . '/' . $short_file_path;
if ( file_exists( $real_file ) ) {
wp_delete_file( $real_file );
self::debug( 'deleted ' . $real_file );
do_action( 'litespeed_media_del', $short_file_path, $post_id );
* @param string $short_file_path Old relative path.
* @param string $short_file_path_new New relative path.
* @param int $post_id Post ID.
public function rename( $short_file_path, $short_file_path_new, $post_id ) {
$real_file = $this->_wp_upload_dir['basedir'] . '/' . $short_file_path;
$real_file_new = $this->_wp_upload_dir['basedir'] . '/' . $short_file_path_new;
if ( file_exists( $real_file ) ) {
if ( ! $wp_filesystem ) {
require_once ABSPATH . '/wp-admin/includes/file.php';
$wp_filesystem->move( $real_file, $real_file_new, true );
self::debug( 'renamed ' . $real_file . ' to ' . $real_file_new );
do_action( 'litespeed_media_rename', $short_file_path, $short_file_path_new, $post_id );
* Media Admin Menu -> Image Optimization Column Title.
* @param array $posts_columns Existing columns.
* @return array Modified columns.
public function media_row_title( $posts_columns ) {
$posts_columns['imgoptm'] = esc_html__( 'LiteSpeed Optimization', 'litespeed-cache' );
* Media Admin Menu -> Image Optimization Column.
* @param string $column_name Current column name.
* @param int $post_id Post ID.
public function media_row_actions( $column_name, $post_id ) {
if ( 'imgoptm' !== $column_name ) {
do_action( 'litespeed_media_row', $post_id );
* Display image optimization info in the media list row.