* Handles responsive placeholders (LQIP), admin column rendering,
* queueing, and generation logic (local and cloud).
defined( 'WPINC' ) || exit();
class Placeholder extends Base {
const TYPE_GENERATE = 'generate';
* Action type: clear queue.
const TYPE_CLEAR_Q = 'clear_q';
* Whether responsive placeholders are enabled.
private $_conf_placeholder_resp;
* SVG template for responsive placeholders.
private $_conf_placeholder_resp_svg;
* Whether LQIP generation via cloud is enabled.
private $_conf_lqip_qual;
* Minimum width for LQIP generation.
private $_conf_lqip_min_w;
* Minimum height for LQIP generation.
private $_conf_lqip_min_h;
* Background color for SVG placeholders.
private $_conf_placeholder_resp_color;
* Whether LQIP generation is async (queued).
private $_conf_placeholder_resp_async;
* Default placeholder data (fallback).
private $_conf_ph_default;
* In-memory map of generated placeholders for current request.
* @var array<string,string>
private $_placeholder_resp_dict = [];
* Keys currently queued within this request.
* Stats & request summary for throttling.
* @var array<string,mixed>
public function __construct() {
$this->_conf_placeholder_resp = defined( 'LITESPEED_GUEST_OPTM' ) || $this->conf( self::O_MEDIA_PLACEHOLDER_RESP );
$this->_conf_placeholder_resp_svg = $this->conf( self::O_MEDIA_PLACEHOLDER_RESP_SVG );
$this->_conf_lqip = ! defined( 'LITESPEED_GUEST_OPTM' ) && $this->conf( self::O_MEDIA_LQIP );
$this->_conf_lqip_qual = $this->conf( self::O_MEDIA_LQIP_QUAL );
$this->_conf_lqip_min_w = $this->conf( self::O_MEDIA_LQIP_MIN_W );
$this->_conf_lqip_min_h = $this->conf( self::O_MEDIA_LQIP_MIN_H );
$this->_conf_placeholder_resp_async = $this->conf( self::O_MEDIA_PLACEHOLDER_RESP_ASYNC );
$this->_conf_placeholder_resp_color = $this->conf( self::O_MEDIA_PLACEHOLDER_RESP_COLOR );
$this->_conf_ph_default = $this->conf(self::O_MEDIA_LAZY_PLACEHOLDER) ? $this->conf(self::O_MEDIA_LAZY_PLACEHOLDER) : LITESPEED_PLACEHOLDER;
$this->_summary = self::get_summary();
Debug2::debug2( '[LQIP] init' );
add_action( 'litespeed_after_admin_init', [ $this, 'after_admin_init' ] );
* Display column in Media.
public function after_admin_init() {
if ( $this->_conf_lqip ) {
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_lqip', [ $this, 'media_row_con' ] );
* Media Admin Menu -> LQIP column header.
* @param array<string,string> $posts_columns Columns.
* @return array<string,string>
public function media_row_title( $posts_columns ) {
$posts_columns['lqip'] = __( 'LQIP', 'litespeed-cache' );
* Media Admin Menu -> LQIP Column renderer trigger.
* @param string $column_name Column name.
* @param int $post_id Attachment ID.
public function media_row_actions( $column_name, $post_id ) {
if ( 'lqip' !== $column_name ) {
do_action( 'litespeed_media_row_lqip', $post_id );
* @param int $post_id Attachment ID.
public function media_row_con( $post_id ) {
$meta_value = wp_get_attachment_metadata( $post_id );
if ( empty( $meta_value['file'] ) ) {
$all_sizes = [ $meta_value['file'] ];
$size_path = pathinfo( $meta_value['file'], PATHINFO_DIRNAME ) . '/';
if ( ! empty( $meta_value['sizes'] ) && is_array( $meta_value['sizes'] ) ) {
foreach ( $meta_value['sizes'] as $v ) {
if ( ! empty( $v['file'] ) ) {
$all_sizes[] = $size_path . $v['file'];
foreach ( $all_sizes as $short_path ) {
$lqip_folder = LITESPEED_STATIC_DIR . '/lqip/' . $short_path;
if ( is_dir( $lqip_folder ) ) {
Debug2::debug( '[LQIP] Found folder: ' . $short_path );
foreach ( scandir( $lqip_folder ) as $v ) {
if ( '.' === $v || '..' === $v ) {
if ( 0 === $total_files ) {
echo '<div class="litespeed-media-lqip"><img src="' .
esc_url( Str::trim_quotes( File::read( $lqip_folder . '/' . $v ) ) ) .
esc_attr( sprintf( __( 'LQIP image preview for size %s', 'litespeed-cache' ), $v ) ) .
echo '<div class="litespeed-media-size"><a href="' . esc_url( Str::trim_quotes( File::read( $lqip_folder . '/' . $v ) ) ) . '" target="_blank">' . esc_html( $v ) . '</a></div>';
if ( 0 === $total_files ) {
* Replace image HTML with placeholder-based lazy version.
* @param string $html Original <img> HTML.
* @param string $src Image source URL.
* @param string $size Requested size (e.g. "300x200").
* @return string Modified HTML.
public function replace( $html, $src, $size ) {
// Check if need to enable responsive placeholder or not.
$ph_candidate = $this->_placeholder( $src, $size );
$this_placeholder = $ph_candidate ? $ph_candidate : $this->_conf_ph_default;
if ( $this->_conf_lqip && $this_placeholder !== $this->_conf_ph_default ) {
Debug2::debug2( '[LQIP] Use resp LQIP [size] ' . $size );
$additional_attr = ' data-placeholder-resp="' . esc_attr( Str::trim_quotes( $size ) ) . '"';
$snippet = ( defined( 'LITESPEED_GUEST_OPTM' ) || $this->conf( self::O_OPTM_NOSCRIPT_RM ) ) ? '' : '<noscript>' . $html . '</noscript>';
'<img data-lazyloaded="1"' . $additional_attr . ' src="' . Str::trim_quotes($this_placeholder) . '" ',
// $html = str_replace( array( ' src=', ' srcset=', ' sizes=' ), array( ' data-src=', ' data-srcset=', ' data-sizes=' ), $html );
// $html = str_replace( '<img ', '<img data-lazyloaded="1"' . $additional_attr . ' src="' . esc_url( Str::trim_quotes( $this_placeholder ) ) . '" ', $html );
$snippet = $html . $snippet;
* Generate responsive placeholder (or schedule generation).
* @param string $src Image source URL.
* @param string $size Size string "WIDTHxHEIGHT".
* @return string|false Data URL placeholder or false.
private function _placeholder( $src, $size ) {
// Low Quality Image Placeholders.
Debug2::debug2( '[LQIP] no size ' . $src );
if ( ! $this->_conf_placeholder_resp ) {
// If use local generator.
if ( ! $this->_conf_lqip || ! $this->_lqip_size_check( $size ) ) {
return $this->_generate_placeholder_locally( $size );
Debug2::debug2( '[LQIP] Resp LQIP process [src] ' . $src . ' [size] ' . $size );
$arr_key = $size . ' ' . $src;
// Check if its already in dict or not.
if ( ! empty( $this->_placeholder_resp_dict[ $arr_key ] ) ) {
Debug2::debug2( '[LQIP] already in dict' );
return $this->_placeholder_resp_dict[ $arr_key ];
// Need to generate the responsive placeholder.
$placeholder_realpath = $this->_placeholder_realpath( $src, $size ); // todo: give offload API.
if ( file_exists( $placeholder_realpath ) ) {
Debug2::debug2( '[LQIP] file exists' );
$this->_placeholder_resp_dict[ $arr_key ] = File::read( $placeholder_realpath );
return $this->_placeholder_resp_dict[ $arr_key ];
// Prevent repeated requests in same request.
if ( in_array( $arr_key, $this->_ph_queue, true ) ) {
Debug2::debug2( '[LQIP] file bypass generating due to in queue' );
return $this->_generate_placeholder_locally( $size );
$hit = Utility::str_hit_array( $src, $this->conf( self::O_MEDIA_LQIP_EXC ) );
Debug2::debug2( '[LQIP] file bypass generating due to exclude setting [hit] ' . $hit );
return $this->_generate_placeholder_locally( $size );
$this->_ph_queue[] = $arr_key;
// Send request to generate placeholder.
if ( ! $this->_conf_placeholder_resp_async ) {
// If requested recently, bypass.
if ( $this->_summary && ! empty( $this->_summary['curr_request'] ) && ( time() - (int) $this->_summary['curr_request'] ) < 300 ) {
Debug2::debug2( '[LQIP] file bypass generating due to interval limit' );
$this->_placeholder_resp_dict[ $arr_key ] = $this->_generate_placeholder( $arr_key );
return $this->_placeholder_resp_dict[ $arr_key ];
// Prepare default svg placeholder as tmp placeholder.
$tmp_placeholder = $this->_generate_placeholder_locally( $size );
// Store it to prepare for cron.
$queue = $this->load_queue( 'lqip' );
if ( in_array( $arr_key, $queue, true ) ) {
Debug2::debug2( '[LQIP] already in queue' );
if ( count( $queue ) > 500 ) {
Debug2::debug2( '[LQIP] queue is full' );
$this->save_queue( 'lqip', $queue );
Debug2::debug( '[LQIP] Added placeholder queue' );
* Generate realpath of placeholder file.
* @param string $src Image source URL.
* @param string $size Size string "WIDTHxHEIGHT".
* @return string Absolute file path.
private function _placeholder_realpath( $src, $size ) {
// Use LQIP Cloud generator, each image placeholder will be separately stored.
// Compatibility with WebP and AVIF.
$src = Utility::drop_webp( $src );
$filepath_prefix = $this->_build_filepath_prefix( 'lqip' );
// External images will use cache folder directly.
$domain = wp_parse_url( $src, PHP_URL_HOST );
if ( $domain && ! Utility::internal( $domain ) ) {
// todo: need to improve `util:internal()` to include `CDN::internal()`
return LITESPEED_STATIC_DIR . $filepath_prefix . 'remote/' . substr( $md5, 0, 1 ) . '/' . substr( $md5, 1, 1 ) . '/' . $md5 . '.' . $size;
$short_path = Utility::att_short_path( $src );
return LITESPEED_STATIC_DIR . $filepath_prefix . $short_path . '/' . $size;
* Cron placeholder generation.
* @param bool $do_continue If true, process full queue in one run.
public static function cron( $do_continue = false ) {
$_instance = self::cls();
$queue = $_instance->load_queue( 'lqip' );
// For cron, need to check request interval too.
if ( ! empty( $_instance->_summary['curr_request'] ) && ( time() - (int) $_instance->_summary['curr_request'] ) < 300 ) {
Debug2::debug( '[LQIP] Last request not done' );
foreach ( $queue as $v ) {
Debug2::debug( '[LQIP] cron job [size] ' . $v );
$res = $_instance->_generate_placeholder( $v, true );
// Exit queue if out of quota.
if ( 'out_of_quota' === $res ) {
// Only request first one unless continuing.
* Generate placeholder locally (SVG).
* @param string $size Size string "WIDTHxHEIGHT".
* @return string Data URL for SVG placeholder.
private function _generate_placeholder_locally( $size ) {
Debug2::debug2( '[LQIP] _generate_placeholder local [size] ' . $size );
$size = explode( 'x', $size );
[ '{width}', '{height}', '{color}' ],
[ (int) $size[0], (int) $size[1], $this->_conf_placeholder_resp_color ],
$this->_conf_placeholder_resp_svg
// phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_encode
return 'data:image/svg+xml;base64,' . base64_encode( $svg );
* Send to LiteSpeed API to generate placeholder (and persist).
* @param string $raw_size_and_src Concatenated "SIZE SRC".
* @param bool $from_cron If true, called from cron context.
* @return string Data URL placeholder.
private function _generate_placeholder( $raw_size_and_src, $from_cron = false ) {
// Parse containing size and src info.
$size_and_src = explode( ' ', $raw_size_and_src, 2 );