<?php
/**
 * Featured Image Functions
 *
 * Funciones para manejo de imágenes destacadas con comportamiento configurable.
 * Sin placeholders - solo muestra imagen si existe.
 * Issue #10 - Imágenes destacadas configurables
 *
 * @package ROI_Theme
 * @since 1.0.0
 */

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

/**
 * Obtiene la imagen destacada de un post con configuración respetada
 *
 * Retorna HTML de la imagen destacada verificando:
 * - Si las imágenes destacadas están habilitadas globalmente
 * - Si el post tiene una imagen destacada asignada
 * - Retorna HTML de la imagen o cadena vacía (sin placeholder)
 *
 * Tamaños disponibles:
 * - roi-featured-large: 1200x600 (para single posts)
 * - roi-featured-medium: 800x400 (para archives)
 * - roi-thumbnail: 400x300 (para widgets/sidebars)
 *
 * @param int|null $post_id ID del post (null = post actual)
 * @param string $size Tamaño de imagen registrado (default: roi-featured-large)
 * @param array $attr Atributos HTML adicionales para la imagen
 * @param bool $force_show Forzar mostrar ignorando configuración (default: false)
 * @return string HTML de la imagen o cadena vacía
 */
function roi_get_featured_image($post_id = null, $size = 'roi-featured-large', $attr = array(), $force_show = false) {
    // Obtener ID del post actual si no se especifica
    if (!$post_id) {
        $post_id = get_the_ID();
    }

    // Si no hay ID válido, retornar vacío
    if (!$post_id) {
        return '';
    }

    // Verificar si el post tiene imagen destacada
    if (!has_post_thumbnail($post_id)) {
        return ''; // No placeholder - retornar vacío
    }

    // Verificar que el archivo físico exista, no solo el attachment ID
    $thumbnailId = get_post_thumbnail_id($post_id);
    $filePath = get_attached_file($thumbnailId);
    if (empty($filePath) || !file_exists($filePath)) {
        return ''; // Archivo no existe en servidor
    }

    // Obtener tipo de post
    $post_type = get_post_type($post_id);

    // Verificar configuración global desde BD (Clean Architecture)
    if (!$force_show) {
        // Leer configuración desde wp_roi_theme_component_settings
        $is_enabled = roi_get_component_setting('featured-image', 'visibility', 'is_enabled', true);
        $show_on_pages = roi_get_component_setting('featured-image', 'visibility', 'show_on_pages', 'posts');

        if (!$is_enabled) {
            return '';
        }

        // Verificar tipo de contenido según configuración
        if ($show_on_pages === 'posts' && $post_type !== 'post') {
            return '';
        }
        if ($show_on_pages === 'pages' && $post_type !== 'page') {
            return '';
        }
        // 'all' = mostrar en todo
    }

    // Atributos por defecto con Bootstrap img-fluid
    $default_attr = array(
        'class' => 'img-fluid featured-image',
        'loading' => 'lazy',
        'alt' => ''
    );

    // Merge de atributos
    $attr = wp_parse_args($attr, $default_attr);

    // Si no hay alt text específico, usar el título del post
    if (empty($attr['alt'])) {
        $attr['alt'] = get_the_title($post_id);
    }

    // Obtener HTML de la imagen
    $thumbnail = get_the_post_thumbnail($post_id, $size, $attr);

    // Si no hay thumbnail, retornar vacío
    if (empty($thumbnail)) {
        return '';
    }

    // Retornar HTML de la imagen sin contenedor adicional
    return $thumbnail;
}

/**
 * Muestra la imagen destacada de un post
 *
 * Template tag para usar directamente en templates.
 * Echo wrapper de roi_get_featured_image().
 *
 * Uso en templates:
 * <?php roi_the_featured_image(); ?>
 * <?php roi_the_featured_image(null, 'roi-featured-medium'); ?>
 *
 * @param int|null $post_id ID del post (null = post actual)
 * @param string $size Tamaño de imagen registrado
 * @param array $attr Atributos HTML adicionales
 * @param bool $force_show Forzar mostrar ignorando configuración
 */
function roi_the_featured_image($post_id = null, $size = 'roi-featured-large', $attr = array(), $force_show = false) {
    echo roi_get_featured_image($post_id, $size, $attr, $force_show);
}

/**
 * Obtiene HTML de thumbnail para archives y loops
 *
 * Versión optimizada para listados con tamaño medium y link al post.
 * Incluye clases responsive de Bootstrap.
 *
 * @param int|null $post_id ID del post (null = post actual)
 * @param bool $with_link Envolver en enlace al post (default: true)
 * @return string HTML del thumbnail o cadena vacía
 */
function roi_get_post_thumbnail($post_id = null, $with_link = true) {
    // Obtener ID del post actual si no se especifica
    if (!$post_id) {
        $post_id = get_the_ID();
    }

    // Si no hay ID válido, retornar vacío
    if (!$post_id) {
        return '';
    }

    // Verificar si el post tiene imagen destacada
    if (!has_post_thumbnail($post_id)) {
        return ''; // No placeholder - retornar vacío
    }

    // Verificar que el archivo físico exista
    $thumbnailId = get_post_thumbnail_id($post_id);
    $filePath = get_attached_file($thumbnailId);
    if (empty($filePath) || !file_exists($filePath)) {
        return '';
    }

    // Obtener la imagen con clases Bootstrap
    $image = get_the_post_thumbnail($post_id, 'roi-featured-medium', array(
        'class' => 'img-fluid post-thumbnail',
        'loading' => 'lazy',
        'alt' => get_the_title($post_id)
    ));

    // Si no hay imagen, retornar vacío
    if (!$image) {
        return '';
    }

    // Construir HTML
    $html = '';

    if ($with_link) {
        $html .= '<a href="' . esc_url(get_permalink($post_id)) . '" class="post-thumbnail-link d-block" aria-label="' . esc_attr(get_the_title($post_id)) . '">';
    }

    $html .= $image;

    if ($with_link) {
        $html .= '</a>';
    }

    return $html;
}

/**
 * Muestra el thumbnail del post para archives
 *
 * Template tag para usar directamente en template-parts.
 * Echo wrapper de roi_get_post_thumbnail().
 *
 * Uso en templates:
 * <?php roi_the_post_thumbnail(); ?>
 * <?php roi_the_post_thumbnail(null, false); // sin link ?>
 *
 * @param int|null $post_id ID del post (null = post actual)
 * @param bool $with_link Envolver en enlace al post
 */
function roi_the_post_thumbnail($post_id = null, $with_link = true) {
    echo roi_get_post_thumbnail($post_id, $with_link);
}

/**
 * Obtiene HTML de thumbnail pequeño para widgets/sidebars
 *
 * Versión mini para listados compactos en sidebars.
 * Usa el tamaño roi-thumbnail (400x300).
 *
 * @param int|null $post_id ID del post (null = post actual)
 * @param bool $with_link Envolver en enlace al post (default: true)
 * @return string HTML del thumbnail o cadena vacía
 */
function roi_get_post_thumbnail_small($post_id = null, $with_link = true) {
    // Obtener ID del post actual si no se especifica
    if (!$post_id) {
        $post_id = get_the_ID();
    }

    // Si no hay ID válido, retornar vacío
    if (!$post_id) {
        return '';
    }

    // Verificar si el post tiene imagen destacada
    if (!has_post_thumbnail($post_id)) {
        return ''; // No placeholder - retornar vacío
    }

    // Verificar que el archivo físico exista
    $thumbnailId = get_post_thumbnail_id($post_id);
    $filePath = get_attached_file($thumbnailId);
    if (empty($filePath) || !file_exists($filePath)) {
        return '';
    }

    // Obtener la imagen
    $image = get_the_post_thumbnail($post_id, 'roi-thumbnail', array(
        'class' => 'img-fluid post-thumbnail-small',
        'loading' => 'lazy',
        'alt' => get_the_title($post_id)
    ));

    // Si no hay imagen, retornar vacío
    if (!$image) {
        return '';
    }

    // Construir HTML
    $html = '';

    if ($with_link) {
        $html .= '<a href="' . esc_url(get_permalink($post_id)) . '" class="post-thumbnail-link-small d-block" aria-label="' . esc_attr(get_the_title($post_id)) . '">';
    }

    $html .= $image;

    if ($with_link) {
        $html .= '</a>';
    }

    return $html;
}

/**
 * Muestra el thumbnail pequeño del post
 *
 * Template tag para usar en widgets y sidebars.
 * Echo wrapper de roi_get_post_thumbnail_small().
 *
 * @param int|null $post_id ID del post (null = post actual)
 * @param bool $with_link Envolver en enlace al post
 */
function roi_the_post_thumbnail_small($post_id = null, $with_link = true) {
    echo roi_get_post_thumbnail_small($post_id, $with_link);
}

/**
 * Verifica si se debe mostrar la imagen destacada según configuración
 *
 * Función helper para usar en condicionales de templates.
 * Útil para estructuras if/else en templates.
 *
 * Uso en templates:
 * <?php if (roi_should_show_featured_image()): ?>
 *     <div class="has-thumbnail">...</div>
 * <?php endif; ?>
 *
 * @param int|null $post_id ID del post (null = post actual)
 * @return bool True si debe mostrarse, false en caso contrario
 */
function roi_should_show_featured_image($post_id = null) {
    // Obtener ID del post actual si no se especifica
    if (!$post_id) {
        $post_id = get_the_ID();
    }

    // Si no hay ID válido, retornar false
    if (!$post_id) {
        return false;
    }

    // Verificar si el post tiene imagen destacada
    if (!has_post_thumbnail($post_id)) {
        return false;
    }

    // Verificar que el archivo físico exista
    $thumbnailId = get_post_thumbnail_id($post_id);
    $filePath = get_attached_file($thumbnailId);
    if (empty($filePath) || !file_exists($filePath)) {
        return false;
    }

    // Obtener tipo de post
    $post_type = get_post_type($post_id);

    // Leer configuración desde BD (Clean Architecture)
    $is_enabled = roi_get_component_setting('featured-image', 'visibility', 'is_enabled', true);
    $show_on_pages = roi_get_component_setting('featured-image', 'visibility', 'show_on_pages', 'posts');

    if (!$is_enabled) {
        return false;
    }

    // Verificar tipo de contenido según configuración
    if ($show_on_pages === 'posts' && $post_type !== 'post') {
        return false;
    }
    if ($show_on_pages === 'pages' && $post_type !== 'page') {
        return false;
    }

    return true;
}

/**
 * Obtiene la URL de la imagen destacada
 *
 * Útil para backgrounds CSS o meta tags de redes sociales (Open Graph, Twitter Cards).
 *
 * Uso:
 * $image_url = roi_get_featured_image_url();
 * echo '<div style="background-image: url(' . $image_url . ')"></div>';
 *
 * @param int|null $post_id ID del post (null = post actual)
 * @param string $size Tamaño de imagen registrado (default: roi-featured-large)
 * @return string URL de la imagen o cadena vacía
 */
function roi_get_featured_image_url($post_id = null, $size = 'roi-featured-large') {
    // Obtener ID del post actual si no se especifica
    if (!$post_id) {
        $post_id = get_the_ID();
    }

    // Si no hay ID válido, retornar vacío
    if (!$post_id) {
        return '';
    }

    // Verificar si el post tiene imagen destacada
    if (!has_post_thumbnail($post_id)) {
        return ''; // No placeholder - retornar vacío
    }

    // Verificar que el archivo físico exista
    $thumbnailId = get_post_thumbnail_id($post_id);
    $filePath = get_attached_file($thumbnailId);
    if (empty($filePath) || !file_exists($filePath)) {
        return '';
    }

    // Obtener URL de la imagen
    $image_url = get_the_post_thumbnail_url($post_id, $size);

    return $image_url ? esc_url($image_url) : '';
}

/**
 * Obtiene el contenedor responsive de imagen destacada con aspect ratio
 *
 * Incluye aspect ratio CSS y lazy loading para mejor rendimiento.
 * Evita layout shift (CLS) con ratio predefinido usando Bootstrap ratio utility.
 *
 * Uso en templates:
 * <?php echo roi_get_featured_image_responsive(); ?>
 * <?php echo roi_get_featured_image_responsive(null, 'roi-featured-medium', '16/9'); ?>
 *
 * @param int|null $post_id ID del post (null = post actual)
 * @param string $size Tamaño de imagen registrado (default: roi-featured-large)
 * @param string $aspect_ratio Ratio CSS - '2/1' para 2:1, '16/9', etc. (default: '2/1')
 * @return string HTML del contenedor con imagen o cadena vacía
 */
function roi_get_featured_image_responsive($post_id = null, $size = 'roi-featured-large', $aspect_ratio = '2/1') {
    // Obtener la imagen
    $image = roi_get_featured_image($post_id, $size);

    // Si no hay imagen, retornar vacío
    if (empty($image)) {
        return '';
    }

    // Construir contenedor responsive con Bootstrap ratio y aspect-ratio CSS
    $html = '<div class="featured-image-wrapper ratio" style="--bs-aspect-ratio: ' . esc_attr($aspect_ratio) . '; aspect-ratio: ' . esc_attr($aspect_ratio) . ';">';
    $html .= $image;
    $html .= '</div>';

    return $html;
}

/**
 * Muestra el contenedor responsive de imagen destacada
 *
 * Template tag para usar directamente en templates.
 * Echo wrapper de roi_get_featured_image_responsive().
 *
 * @param int|null $post_id ID del post (null = post actual)
 * @param string $size Tamaño de imagen registrado
 * @param string $aspect_ratio Ratio CSS (ej: '16/9', '2/1')
 */
function roi_the_featured_image_responsive($post_id = null, $size = 'roi-featured-large', $aspect_ratio = '2/1') {
    echo roi_get_featured_image_responsive($post_id, $size, $aspect_ratio);
}

/**
 * Verifica si las imágenes destacadas están habilitadas para un tipo de post
 *
 * Lee configuración desde BD (Clean Architecture)
 *
 * @param string $post_type Tipo de post (vacío = post actual)
 * @return bool True si habilitadas, false en caso contrario
 */
function roi_is_featured_image_enabled($post_type = '') {
    if (empty($post_type)) {
        $post_type = get_post_type();
    }

    if (!$post_type) {
        return true; // Default habilitado
    }

    // Leer configuración desde BD (Clean Architecture)
    $is_enabled = roi_get_component_setting('featured-image', 'visibility', 'is_enabled', true);
    $show_on_pages = roi_get_component_setting('featured-image', 'visibility', 'show_on_pages', 'posts');

    if (!$is_enabled) {
        return false;
    }

    // Verificar tipo de contenido según configuración
    if ($show_on_pages === 'posts' && $post_type !== 'post') {
        return false;
    }
    if ($show_on_pages === 'pages' && $post_type !== 'page') {
        return false;
    }

    return true;
}

// =============================================================================
// NOTA: Customizer eliminado - Clean Architecture
// La configuración de imágenes destacadas se gestiona desde:
// - Admin Panel: Admin/FeaturedImage/Infrastructure/Ui/FeaturedImageFormBuilder.php
// - Base de datos: wp_roi_theme_component_settings (component_name = 'featured-image')
// =============================================================================