Generar y servir compañeros WebP

Para imágenes compatibles que no sean GIF y que todavía no estén en WebP, Image Optimizer crea un archivo WebP junto al archivo original y junto a cada tamaño generado.

El compañero conserva el nombre de archivo original completo y añade .webp:

photo.jpg
photo.jpg.webp

photo-300x200.jpg
photo-300x200.jpg.webp

Reglas de formato

• Los adjuntos JPEG, PNG y AVIF pueden recibir compañeros WebP.
• Una subida WebP se optimiza como WebP y no recibe .webp.webp.
• Los adjuntos GIF no reciben compañeros WebP. Cualquier compañero coincidente se elimina para que un GIF animado no se sustituya por una conversión aplanada.
• Un WebP generado debe ser no vacío y totalmente decodificable antes de reemplazar al compañero anterior. Las conversiones fallidas dejan intacto cualquier compañero existente.

Eliminar un adjunto elimina los compañeros registrados para su archivo principal y sus tamaños generados.

La generación no es la entrega

Este módulo crea los archivos; no reescribe las URL de las imágenes en el HTML de la página ni negocia el soporte del navegador. Para servir un compañero en lugar del original, configura una regla compatible de servidor web, CDN o entrega de imágenes que:

• compruebe si el archivo WebP existe;
• varíe correctamente según el soporte del navegador;
• recurra al formato original como alternativa;
• preserve la separación de caché entre representaciones.

No des por hecho que encontrar .webp en disco demuestre que los visitantes lo reciben.

Verifica ambos lados

1. Sube un JPEG o PNG después de activar Image Optimizer.
2. Confirma que existen compañeros para el archivo principal y los tamaños esperados.
3. Solicita la URL normal de la imagen en un navegador.
4. Inspecciona la respuesta Content-Type y los bytes realmente transferidos.
5. Repite con un cliente que no anuncie soporte para WebP.
6. Elimina el adjunto de prueba y confirma que se eliminan sus compañeros conocidos.

Si faltan archivos, usa Troubleshoot image optimization. Si los archivos existen pero no se sirven, revisa la capa de entrega en lugar de volver a ejecutar la optimización.

API para desarrolladores: un único WebP para imágenes de documentos

Una integración que necesite una única imagen de documento optimizada puede llamar al helper estático mientras Image optimizer está activado:

POM_Tweaks_Image_Optimizer::optimize_private_webp(
    string $source,
    string $destination,
    int $max_dimension = 1300
): array;

Comprueba is_callable(array('POM_Tweaks_Image_Optimizer', 'optimize_private_webp')) antes de llamarlo. Desactivar el ajuste hace que la API no esté disponible.

El origen y el destino son rutas de archivo locales. El destino debe tener una extensión .webp, residir en un directorio existente y no existir ya. La persona que llama debe autorizar la operación, usar un directorio con una protección de acceso adecuada y limpiar su propio archivo de origen. El helper no registra un adjunto, no actualiza los metadatos del medio, no crea archivos compañeros ni elimina su origen.

Su contrato específico para documentos es:

• Acepta PNG, JPEG, GIF o WebP de como máximo 4 MiB, 12.000 píxeles por lado y 40 megapíxeles.
• Escribe un WebP cuyo lado más largo mida como máximo $max_dimension, que debe estar entre 1 y 1300. Las imágenes más pequeñas no se amplían.
• Usa el controlador de imágenes y la cadena de optimización compartidos de Spatie. La conversión usa calidad 85, seguida de una optimización WebP sin pérdida; se conserva el WebP válido más pequeño.
• Optimiza un WebP que ya cumple los requisitos sin otra pasada de codificación con pérdida, de modo que los guardados repetidos del documento no reduzcan progresivamente su calidad.
• Conserva la transparencia y aplica la orientación EXIF compatible antes de redimensionar. Las animaciones GIF se convierten en un único primer fotograma. Los WebP animados y los WebP que contienen metadatos EXIF requieren el controlador Imagick; una decodificación no compatible falla en lugar de cambiar silenciosamente la imagen.
• Requiere el binario del optimizador cwebp. Los fallos de decodificación, optimización, tiempo de espera, permisos y escritura lanzan una excepción y no dejan ningún destino recién creado. Un destino existente nunca se sobrescribe.

Si tiene éxito, el array devuelto contiene los enteros width, height y bytes, además de mime igual a image/webp. Captura Throwable en la integración e informa del fallo sin conservar una alternativa sin procesar. El helper elimina su salida temporal en todos los casos.

Para verificar una integración, procesa una imagen grande, un PNG transparente y un WebP ya optimizado. Comprueba las dimensiones y el MIME devueltos, repite la operación WebP en un destino nuevo y confirma que un destino existente permanece sin cambios. Esta API no modifica la política de 2560 píxeles ni el comportamiento de archivos compañeros de las subidas normales de adjuntos de WordPress.