roi-theme/wp-content/themes/apus-theme/inc/image-optimization.php

<?php
/**
 * Image Optimization Functions
 *
 * Handles responsive images, WebP/AVIF support, lazy loading, and image preloading.
 *
 * @package Apus_Theme
 * @since 1.0.0
 */

// Exit if accessed directly
if (!defined('ABSPATH')) {
    exit;
}

/**
 * Enable AVIF image support
 */
function apus_enable_avif_support($mime_types) {
    $mime_types['avif'] = 'image/avif';
    return $mime_types;
}
add_filter('upload_mimes', 'apus_enable_avif_support');

/**
 * Add AVIF to allowed file extensions
 */
function apus_allow_avif_extension($types, $file, $filename, $mimes) {
    if (false !== strpos($filename, '.avif')) {
        $types['ext'] = 'avif';
        $types['type'] = 'image/avif';
    }
    return $types;
}
add_filter('wp_check_filetype_and_ext', 'apus_allow_avif_extension', 10, 4);

/**
 * Configure custom image sizes
 * Already defined in functions.php, but we can add more if needed
 */
function apus_setup_additional_image_sizes() {
    // Add support for additional modern image sizes
    add_image_size('apus-hero', 1920, 800, true);          // Hero images
    add_image_size('apus-card', 600, 400, true);           // Card thumbnails
    add_image_size('apus-thumbnail-2x', 800, 600, true);   // Retina thumbnails
}
add_action('after_setup_theme', 'apus_setup_additional_image_sizes');

/**
 * Add custom image sizes to media library dropdown
 */
function apus_custom_image_sizes($sizes) {
    return array_merge($sizes, array(
        'apus-thumbnail' => __('Thumbnail (400x300)', 'apus-theme'),
        'apus-medium' => __('Medium (800x600)', 'apus-theme'),
        'apus-large' => __('Large (1200x900)', 'apus-theme'),
        'apus-featured-large' => __('Featured Large (1200x600)', 'apus-theme'),
        'apus-featured-medium' => __('Featured Medium (800x400)', 'apus-theme'),
        'apus-hero' => __('Hero (1920x800)', 'apus-theme'),
        'apus-card' => __('Card (600x400)', 'apus-theme'),
    ));
}
add_filter('image_size_names_choose', 'apus_custom_image_sizes');

/**
 * Generate srcset and sizes attributes for responsive images
 *
 * @param int $attachment_id Image attachment ID
 * @param string $size Image size
 * @param array $additional_sizes Additional sizes to include in srcset
 * @return array Array with 'srcset' and 'sizes' attributes
 */
function apus_get_responsive_image_attrs($attachment_id, $size = 'full', $additional_sizes = array()) {
    if (empty($attachment_id)) {
        return array('srcset' => '', 'sizes' => '');
    }

    // Get default WordPress srcset
    $srcset = wp_get_attachment_image_srcset($attachment_id, $size);

    // Get default WordPress sizes attribute
    $sizes = wp_get_attachment_image_sizes($attachment_id, $size);

    // Add additional sizes if specified
    if (!empty($additional_sizes)) {
        $srcset_array = array();
        foreach ($additional_sizes as $additional_size) {
            $image = wp_get_attachment_image_src($attachment_id, $additional_size);
            if ($image) {
                $srcset_array[] = $image[0] . ' ' . $image[1] . 'w';
            }
        }
        if (!empty($srcset_array)) {
            $srcset .= ', ' . implode(', ', $srcset_array);
        }
    }

    return array(
        'srcset' => $srcset,
        'sizes' => $sizes,
    );
}

/**
 * Output responsive image with lazy loading
 *
 * @param int $attachment_id Image attachment ID
 * @param string $size Image size
 * @param array $attr Additional image attributes
 * @param bool $lazy Enable lazy loading (default: true)
 * @return string Image HTML
 */
function apus_get_responsive_image($attachment_id, $size = 'full', $attr = array(), $lazy = true) {
    if (empty($attachment_id)) {
        return '';
    }

    // Get responsive attributes
    $responsive_attrs = apus_get_responsive_image_attrs($attachment_id, $size);

    // Merge default attributes with custom ones
    $default_attr = array(
        'loading' => $lazy ? 'lazy' : 'eager',
        'decoding' => 'async',
    );

    // Add srcset and sizes if available
    if (!empty($responsive_attrs['srcset'])) {
        $default_attr['srcset'] = $responsive_attrs['srcset'];
    }
    if (!empty($responsive_attrs['sizes'])) {
        $default_attr['sizes'] = $responsive_attrs['sizes'];
    }

    $attr = array_merge($default_attr, $attr);

    return wp_get_attachment_image($attachment_id, $size, false, $attr);
}

/**
 * Enable lazy loading by default for all images
 */
function apus_add_lazy_loading_to_images($attr, $attachment, $size) {
    // Don't add lazy loading if explicitly disabled
    if (isset($attr['loading']) && $attr['loading'] === 'eager') {
        return $attr;
    }

    // Add lazy loading by default
    if (!isset($attr['loading'])) {
        $attr['loading'] = 'lazy';
    }

    // Add async decoding for better performance
    if (!isset($attr['decoding'])) {
        $attr['decoding'] = 'async';
    }

    return $attr;
}
add_filter('wp_get_attachment_image_attributes', 'apus_add_lazy_loading_to_images', 10, 3);

/**
 * Add lazy loading to content images
 */
function apus_add_lazy_loading_to_content($content) {
    // Don't process if empty
    if (empty($content)) {
        return $content;
    }

    // Add loading="lazy" to images that don't have it
    $content = preg_replace('/<img(?![^>]*loading=)/', '<img loading="lazy" decoding="async"', $content);

    return $content;
}
add_filter('the_content', 'apus_add_lazy_loading_to_content', 20);

/**
 * Preload critical images (LCP images)
 * This should be called for above-the-fold images
 *
 * @param int $attachment_id Image attachment ID
 * @param string $size Image size
 */
function apus_preload_image($attachment_id, $size = 'full') {
    if (empty($attachment_id)) {
        return;
    }

    $image_src = wp_get_attachment_image_src($attachment_id, $size);
    if (!$image_src) {
        return;
    }

    $srcset = wp_get_attachment_image_srcset($attachment_id, $size);
    $sizes = wp_get_attachment_image_sizes($attachment_id, $size);

    // Detect image format
    $image_url = $image_src[0];
    $image_type = 'image/jpeg'; // default

    if (strpos($image_url, '.avif') !== false) {
        $image_type = 'image/avif';
    } elseif (strpos($image_url, '.webp') !== false) {
        $image_type = 'image/webp';
    } elseif (strpos($image_url, '.png') !== false) {
        $image_type = 'image/png';
    }

    // Build preload link
    $preload = sprintf(
        '<link rel="preload" as="image" href="%s" type="%s"',
        esc_url($image_url),
        esc_attr($image_type)
    );

    if ($srcset) {
        $preload .= sprintf(' imagesrcset="%s"', esc_attr($srcset));
    }
    if ($sizes) {
        $preload .= sprintf(' imagesizes="%s"', esc_attr($sizes));
    }

    $preload .= '>';

    echo $preload . "\n";
}

/**
 * Preload featured image for single posts (LCP optimization)
 */
function apus_preload_featured_image() {
    // Only on single posts/pages with featured images
    if (!is_singular() || !has_post_thumbnail()) {
        return;
    }

    // Get the featured image ID
    $thumbnail_id = get_post_thumbnail_id();

    // Determine the size based on the post type
    $size = 'apus-featured-large';

    // Preload the image
    apus_preload_image($thumbnail_id, $size);
}
add_action('wp_head', 'apus_preload_featured_image', 5);

/**
 * Enable fetchpriority attribute for featured images
 */
function apus_add_fetchpriority_to_featured_image($attr, $attachment, $size) {
    // Only add fetchpriority="high" to featured images on singular pages
    if (is_singular() && get_post_thumbnail_id() === $attachment->ID) {
        $attr['fetchpriority'] = 'high';
        $attr['loading'] = 'eager'; // Don't lazy load LCP images
    }

    return $attr;
}
add_filter('wp_get_attachment_image_attributes', 'apus_add_fetchpriority_to_featured_image', 20, 3);

/**
 * Optimize image quality for uploads
 */
function apus_optimize_image_quality($quality, $mime_type) {
    // Set quality to 85% for better file size without visible quality loss
    if ($mime_type === 'image/jpeg') {
        return 85;
    }
    return $quality;
}
add_filter('jpeg_quality', 'apus_optimize_image_quality', 10, 2);
add_filter('wp_editor_set_quality', 'apus_optimize_image_quality', 10, 2);

/**
 * Add picture element support for WebP/AVIF with fallbacks
 *
 * @param int $attachment_id Image attachment ID
 * @param string $size Image size
 * @param array $attr Additional attributes
 * @return string Picture element HTML
 */
function apus_get_picture_element($attachment_id, $size = 'full', $attr = array()) {
    if (empty($attachment_id)) {
        return '';
    }

    $image_src = wp_get_attachment_image_src($attachment_id, $size);
    if (!$image_src) {
        return '';
    }

    $srcset = wp_get_attachment_image_srcset($attachment_id, $size);
    $sizes = wp_get_attachment_image_sizes($attachment_id, $size);
    $alt = get_post_meta($attachment_id, '_wp_attachment_image_alt', true);

    // Default attributes
    $default_attr = array(
        'loading' => 'lazy',
        'decoding' => 'async',
        'alt' => $alt,
    );

    $attr = array_merge($default_attr, $attr);

    // Build picture element
    $picture = '<picture>';

    // Add AVIF source if available
    $avif_url = str_replace(array('.jpg', '.jpeg', '.png', '.webp'), '.avif', $image_src[0]);
    if ($avif_url !== $image_src[0]) {
        $picture .= sprintf(
            '<source type="image/avif" srcset="%s" sizes="%s">',
            esc_attr($avif_url),
            esc_attr($sizes)
        );
    }

    // Add WebP source if available
    $webp_url = str_replace(array('.jpg', '.jpeg', '.png'), '.webp', $image_src[0]);
    if ($webp_url !== $image_src[0]) {
        $picture .= sprintf(
            '<source type="image/webp" srcset="%s" sizes="%s">',
            esc_attr($webp_url),
            esc_attr($sizes)
        );
    }

    // Fallback img tag
    $picture .= wp_get_attachment_image($attachment_id, $size, false, $attr);
    $picture .= '</picture>';

    return $picture;
}

/**
 * Disable big image threshold for high-quality images
 * WordPress 5.3+ scales down images larger than 2560px by default
 * Uncomment to disable this behavior if you need full-size images
 */
// add_filter('big_image_size_threshold', '__return_false');

/**
 * Set maximum srcset image width
 */
function apus_max_srcset_image_width($max_width, $size_array) {
    // Limit srcset to images up to 2560px wide
    return 2560;
}
add_filter('max_srcset_image_width', 'apus_max_srcset_image_width', 10, 2);