Image Optimization Overview

This guide reflects the image optimizations implemented in Image.php and related Image Converter integration. All features are controlled by configuration flags in SysConfig::$config.

Lazy Loading

When img_lazyload is enabled, ZiziCache sets loading="lazy" for most images and marks a configurable number of above‑the‑fold images as eager.

• img_lazyload_exclude_count_desktop — number of eager images on desktop.
• img_lazyload_exclude_count_mobile — number of eager images on mobile.
• Fallback: img_lazyload_exclude_count (legacy single value).

Images matching exclusion keywords (default: eager, skip-lazy plus img_lazyload_excludes) are forced to loading="eager".

Width & Height Injection

When img_width_height is enabled, ZiziCache adds missing dimensions based on:

• Filename hints (e.g., image-300x200.jpg).
• Actual file dimensions (local images).
• SVG width/height or viewBox attributes.

This helps prevent layout shifts by preserving aspect ratios.

Responsive Images (srcset)

When img_responsive is enabled, ZiziCache generates srcset for local images and sets sizes="auto":

• Uses wp_get_attachment_image_srcset when an attachment ID can be resolved.
• Falls back to manual size guessing based on registered thumbnails.
• Skips SVG images.
• Respects disabled thumbnail sizes when thumbnail_prevention_enabled is active.

Preloading Above‑the‑Fold Images

When img_preload is enabled, ZiziCache preloads images marked as eager:

• Creates with optional imagesrcset and imagesizes.
• Inserted after or after if needed.
• Fixes Elementor/Bricks srcset URL format for preloads.

Priority Hints

When img_priority_hints is enabled, ZiziCache sets fetchpriority:

• high for eager images.
• low for other images (unless already high).

Automatic LCP Image Marking

When img_auto_lcp is enabled, ZiziCache reads stored LCP data (transient zizicache_lcp_data) and marks the detected LCP image as:

• loading="eager"
• fetchpriority="high"
• decoding="sync"

LCP data is matched by URL and device type (desktop/mobile).

Localhost Gravatar

When img_localhost_gravatar is enabled, Gravatar images are downloaded and served locally from the cache directory. SSRF protections are applied to block private/reserved IP ranges.

Background Image Lazy Loading

When img_lazyload is enabled, ZiziCache can lazy load background images:

• Inline style backgrounds are converted to data-lazy-style.
• Elements with class="lazy-bg" are converted to data-lazy-class.

This requires frontend handling by ZiziCache’s core script.

AVIF/WebP Frontend Serving (Image Converter)

If the Image Converter module is enabled and image_converter_frontend_serve is true, ZiziCache can rewrite image src to serve AVIF or WebP when:

• The browser supports the format.
• Converted files exist and metadata is present for the attachment.
• The image is not SVG/GIF and not already optimized.

Troubleshooting

• Missing srcset: ensure the image has width/height and is hosted on the same domain.
• Lazy loading excluded incorrectly: review img_lazyload_excludes and exclude counts.
• Wrong format served: verify Image Converter metadata and that AVIF/WebP files exist.