ImageAPI Optimize WebP
Provides a WebP processor for the ImageAPI Optimize module that automatically creates WebP derivatives alongside original image style derivatives.
imageapi_optimize_webp
Install
composer require 'drupal/imageapi_optimize_webp:^2.1'
composer require 'drupal/imageapi_optimize_webp:^2.0'
Overview
ImageAPI Optimize WebP extends the ImageAPI Optimize module by providing a WebP Deriver processor. When this processor is added to an optimization pipeline, it automatically generates WebP versions of styled images alongside the original format derivatives.
WebP is a modern image format developed by Google that provides superior compression for images on the web. This module enables Drupal sites to serve WebP images to browsers that support it, resulting in faster page loads and reduced bandwidth consumption while maintaining image quality.
The module works by intercepting image style generation and creating a .webp copy of each processed image. It also overrides the image style download controller to properly serve WebP derivatives when requested. A companion sub-module integrates this functionality with Drupal's Responsive Images module, automatically adding WebP sources to responsive image picture elements.
Features
- Provides a WebP Deriver processor plugin for ImageAPI Optimize pipelines
- Automatically generates WebP derivatives when image styles are created
- Configurable image quality setting (1-100%) for WebP compression
- Custom image style download controller that properly serves WebP images with correct Content-Type headers
- Automatic cleanup of WebP derivatives when image styles are flushed
- Sub-module for seamless integration with Drupal core Responsive Images
- Supports both public and private file systems
- Works with GD image library for WebP conversion
Use Cases
Site-wide WebP Image Optimization
Configure a single Image Optimize Pipeline with the WebP Deriver processor and set it as the sitewide default. All image styles will automatically generate WebP derivatives, reducing bandwidth usage across your entire site without any additional configuration per image style.
Selective WebP for Specific Image Styles
Create a dedicated pipeline with the WebP Deriver for specific high-traffic image styles (such as hero images or product galleries) while leaving other image styles using standard formats. Assign this pipeline only to the image styles that would benefit most from WebP compression.
Responsive Images with WebP Support
Enable the ImageAPI Optimize WebP Responsive sub-module to automatically serve WebP images to supporting browsers when using responsive images. The module adds WebP sources to the picture element, allowing modern browsers to automatically select the WebP version while older browsers fall back to the original format.
Balancing Quality and File Size
Adjust the quality setting per pipeline to find the optimal balance between visual quality and file size reduction. For photographic content, 75-85% quality typically provides excellent results. For simpler graphics, lower values like 60-70% may be acceptable with greater file size savings.
Tips
- Start with the default quality of 75% and adjust based on your specific image content and quality requirements
- Use browser developer tools to verify WebP images are being served by checking the Content-Type header in network requests
- Clear image style caches after changing pipeline configurations to regenerate derivatives
- Monitor file system storage as WebP derivatives are stored alongside original format derivatives
- Consider using a CDN that supports WebP content negotiation for additional optimization
Technical Details
Admin Pages 1
/admin/config/media/imageapi-optimize-pipelines
Configure Image Optimize pipelines and add the WebP Deriver processor. This module adds a 'WebP Deriver' option to the processor selection dropdown when creating or editing pipelines.
Hooks 2
hook_entity_type_alter
Replaces the ImageAPIOptimizePipeline entity class with a custom implementation that handles WebP derivative file management after pipeline processing.
hook_image_style_flush
Deletes WebP derivative files when an image style is flushed. Ensures that .webp files are cleaned up alongside their source derivatives.
Troubleshooting 4
Ensure PHP GD library is installed with WebP support. Check that the WebP Deriver processor is added to your pipeline and the pipeline is assigned to your image styles. Verify the files directory is writable.
Clear Drupal caches to ensure the route subscriber has properly overridden image style routes. Check that the source image exists and can generate a derivative.
The module includes a fix for WebP files with odd byte sizes. If issues persist, check GD library version and ensure adequate memory limits for image processing.
Enable the ImageAPI Optimize WebP Responsive sub-module. Ensure the responsive image style uses image styles that have pipelines with the WebP Deriver processor assigned.