Image Optimize
A framework for image optimization that provides pipelines with processors to optimize images, with built-in integration for Drupal core image styles.
imageapi_optimize
Install
composer require 'drupal/imageapi_optimize:^4.1'
Overview
The Image Optimize module provides a comprehensive framework for image optimization in Drupal. It introduces a system of 'pipelines' where each pipeline contains multiple 'processors' that are applied sequentially to optimize images.
To optimize an image, it is passed to a pipeline which orchestrates each processor applying itself to the image in order of their configured weight. For example, you may have one pipeline for lossless optimization that removes unnecessary metadata from images, and another lossy pipeline that applies re-compression via a third-party webservice.
The module provides built-in support for Drupal image styles. After the usual image style effects have been applied, the derivative image is automatically passed through a configurable optimization pipeline. You can set a sitewide default pipeline or configure a specific pipeline for each image style individually.
The module itself does not include any processor plugins - you need to install additional modules that provide actual image optimization processors, such as Image Optimize Binaries, Image Optimize reSmush.it, Image Optimize TinyPNG, or Kraken.
Features
- Create and manage image optimization pipelines with multiple processors
- Drag-and-drop reordering of processors within pipelines
- Weight-based processor execution order
- Set a sitewide default pipeline for all image styles
- Assign specific pipelines to individual image styles
- Automatic integration with Drupal core image styles - derivatives are optimized after effects are applied
- Flush cached images when pipelines are modified
- Replacement pipeline selection when deleting a pipeline
- Extensible plugin system for creating custom image processors
- Support for both configurable and non-configurable processor plugins
- Temporary file management during optimization process
- Cache invalidation integration
- Configuration entity export/import support
Use Cases
Lossless image optimization
Create a pipeline with processors that remove unnecessary metadata from images without reducing quality. This is ideal for production sites where you want smaller file sizes but cannot accept any quality loss. Use processors like jpegtran (for JPEG) and optipng (for PNG) from the Image Optimize Binaries module.
Lossy image compression
Create a pipeline with processors that apply lossy compression for maximum file size reduction. Use a service like TinyPNG or reSmush.it that intelligently compresses images. This is ideal for sites with many images where bandwidth is a concern and some quality loss is acceptable.
Multi-stage optimization pipeline
Create a pipeline with multiple processors in sequence. For example, first use jpegtran to strip metadata, then use jpegoptim to apply lossy compression. The weight system ensures processors run in the correct order.
Different optimization per image style
Assign different pipelines to different image styles. Use aggressive lossy compression for thumbnail styles where quality is less important, and lossless optimization for full-size images where quality matters.
Sitewide default with exceptions
Set a sitewide default pipeline for general optimization, then override it for specific image styles that need different treatment. For example, use lossless optimization as the default but use aggressive compression for gallery thumbnails.
Tips
- Start with a simple lossless optimization pipeline and measure the file size savings before adding lossy compression.
- Use the 'Flush' operation sparingly on production sites as it forces regeneration of all image derivatives.
- The sitewide default pipeline feature allows you to change your optimization strategy globally without editing each image style.
- Processors are executed in weight order - use this to chain multiple optimization steps effectively.
- Test your optimization pipelines with representative images before deploying to ensure acceptable quality and file size.
- For development, you can use '- None -' as the pipeline to skip optimization and speed up testing.
Technical Details
Admin Pages 7
/admin/config/media/imageapi-optimize-pipelines
Main administration page for managing image optimization pipelines. Lists all existing pipelines with their names and provides operations to edit, delete, or flush each pipeline. The page also includes a form to set the sitewide default pipeline that will be used when 'Sitewide default pipeline' is selected in image style configuration.
/admin/config/media/imageapi-optimize-pipelines/add
Form to create a new image optimization pipeline. After creation, you will be redirected to the edit form to add processors.
/admin/config/media/imageapi-optimize-pipelines/manage/{pipeline}
Form to configure an existing pipeline by adding, editing, removing, and reordering processors. Shows a table of all processors in the pipeline with drag-and-drop reordering capability.
/admin/config/media/imageapi-optimize-pipelines/manage/{pipeline}/delete
Confirmation form for deleting a pipeline. If other pipelines exist, you can optionally select a replacement pipeline to update dependent configurations.
/admin/config/media/imageapi-optimize-pipelines/manage/{pipeline}/flush
Confirmation form to flush all cached derivative images that use this pipeline. This forces regeneration of all image derivatives with the current pipeline configuration.
/admin/config/media/image-styles
The core Image styles listing page is enhanced to show an 'Image Optimize Pipeline' column for each style, displaying which pipeline (if any) is assigned to each style.
/admin/config/media/image-styles/manage/{style}
The core image style edit form is enhanced with an Image Optimize Pipeline dropdown that allows you to select which optimization pipeline to apply after all image effects have been processed.
Permissions 1
Hooks 2
hook_imageapi_optimize_processor_info_alter
Allows modules to alter the image optimize processor plugin definitions discovered by the plugin manager.
hook_imageapi_optimize_pipeline_flush
Invoked when a pipeline is flushed, allowing other modules to perform additional cache clearing or cleanup operations.
Troubleshooting 5
Ensure you have at least one processor module installed (e.g., imageapi_optimize_binaries). Verify a pipeline has been created with at least one processor, and that the pipeline is assigned to the image style (either as default or explicitly).
Install a processor module such as imageapi_optimize_binaries, imageapi_optimize_resmushit, or imageapi_optimize_tinypng. The base module does not include any processors.
After modifying a pipeline, you may need to flush the pipeline and regenerate image derivatives. Use the 'Flush' operation on the pipelines list page, or flush the associated image styles.
If you see errors about missing processors, the processor module may need to be re-enabled. The module includes an update hook (8003) that attempts to re-enable processor modules automatically.
Ensure the imageapi_optimize module is properly enabled. The module alters the image style form and entity to add the pipeline field.
Security Notes 3
- The 'Administer Image Optimize pipelines' permission should only be granted to trusted administrators as misconfigured processors could potentially affect site performance.
- When using external services (TinyPNG, reSmush.it, Kraken), images are sent to third-party servers for processing. Consider this when handling sensitive images.
- API keys for external services should be stored securely in configuration and not exposed in version control.