Feature: Next.js-style image optimization for Experience Builder

Image Delivery Flow Architecture

The image optimization feature follows a well-structured flow for delivering optimized images:

1. Component Rendering

When an Experience Builder image component is rendered:

• The component generates optimized URLs with transformation parameters
• The URLs include width, height, format, quality, and a security token
• Example URL: /system/files/xb-styles/public/path/to/image.jpg?w=800&h=600&f=webp&q=80&itok=SECURITY_TOKEN
• For responsive images, multiple sizes are generated in a srcset attribute
• The Twig template may use elements with different sources for various formats

2. URL Processing

When a client requests an optimized image:

• The request is intercepted by PathProcessorResponsiveImages
• The processor extracts parameters from the URL path and query string
• The processor rewrites the path to a controller route pattern
• The ResponsiveImageRoutes service directs the request to the ResponsiveImageController

3. Controller Processing

The ResponsiveImageController handles the image request by:

• Validating the security token using the ImageUrlManager
• Determining the original image path from the request
• Checking if a derivative already exists
• If not, using the ImageStyleManager to generate the derivative
• Setting appropriate caching headers (31536000 seconds, or 1 year)
• Serving the image with the correct Content-Type header

4. Image Transformation

When a new derivative needs to be created:

• The ImageStyleManager determines the correct derivative path
• It then calls the ImageTransformationService to perform the transformations
• The transformation service:
  • Opens the original image using the QualityAwareImageFactory
  • Resizes the image to the requested dimensions
  • Converts the image to the requested format (WebP, AVIF, etc.)
  • Applies the requested quality setting using the QualityAwareImage extensions
  • Saves the derivative to the file system

5. File Storage

Derivative images are stored with a structured pattern:

• Base path: /[scheme]://xb-responsive/
• Dimensions and quality: /[width]x[height]-[quality]/
• Format: /[format]/
• Original path structure: /[original-directory]/[original-filename].[original-ext].[new-ext]
• Example: public://xb-responsive/800x600-80/webp/images/photo.jpg.webp

6. Client Delivery

The optimized image is delivered to the client with:

• The correct Content-Type header for the image format
• Cache headers for efficient browser caching
• If supported, modern formats like WebP or AVIF
• Otherwise, fallback to the original format

7. Quality Control

The quality settings work through:

• The QualityAwareImage class which extends Drupal's core Image class
• A custom JPEG quality application that bypasses Drupal's default quality settings
• Custom toolkit parameter handling that only applies to supported formats

Key Components

1. ImageTransformationService: Performs actual image manipulations
2. QualityAwareImage & QualityAwareImageFactory: Extend Drupal's image handling with quality controls
3. ImageUrlManager: Generates and validates security tokens for images
4. ImageStyleManager: Manages derivative creation and caching
5. PathProcessorResponsiveImages: Handles URL routing for image requests
6. ResponsiveImageController: Serves optimized images
7. ResponsiveImageTwigExtension: Provides Twig functions for templates

The architecture leverages Drupal's existing image handling system while extending it with modern optimization techniques, creating a powerful and flexible image optimization system within the Experience Builder.