README

This bundle extends the existing cmsthumb process with configurable output formats such as webp.

It integrates through the TCMSImage inheritance chain, so normal Twig cmsthumb(...) calls and direct PHP thumbnail calls use the same logic.

Runtime Flow

• cmsthumb(...) still goes through TPkgSnippetRendererFilter::getThumbnail()
• that creates TCMSImage and calls GetThumbnail() or GetCenteredFixedSizeThumbnail()
• if a usable configured format is available, the bundle generates that thumbnail directly in the Chameleon thumb namespace
• otherwise the code stays on the unchanged parent Chameleon thumbnail pipeline

The code also stays on the parent Chameleon pipeline for:

• thumbnails with effects
• fixed-size thumbnails with non-default padding
• fixed-size thumbnails with a non-default background color
• fixed-size thumbnails with non-default stretch behavior
• thumbnail sizes where cms_config_imagemagick.fieldForceJpeg is active

Explicit legacy access:

• Twig: cmsthumblegacy(...)
• PHP: GetLegacyThumbnail(...) / GetLegacyCenteredFixedSizeThumbnail(...)

Configuration

chameleon_system_image_format:
  enabled: true
  default_format: webp
  active_formats:
    - webp
  format_settings:
    webp:
      quality_percent: 85

• default_format is the preferred format
• active_formats is the allowed format list and fallback order
• format_settings is keyed by format name; each handler reads only its own subsection

The public API does not choose a format per individual cmsthumb(...) call. The bundle uses default_format when its handler is usable, otherwise it falls back through active_formats.

The configured-format path also respects the size-dependent legacy database configuration from cms_config_imagemagick where it maps cleanly:

• fieldForceJpeg forces the request back to the legacy path
• fieldQuality overrides the handler quality for that thumbnail size
• fieldGamma and fieldScharpen are applied in the Imagick-based path when possible

Current limitation:

• the GD fallback path only uses the resolved quality value
• gamma and sharpen are not applied in the GD fallback path

Twig And PHP Usage

{{ imageId|cmsthumb(400, 300) }}
{{ imageId|cmsthumblegacy(400, 300) }}

$thumbnail = $image->GetThumbnail(400, 300);
$thumbnail = $image->GetLegacyThumbnail(400, 300);

Cache Behavior

• generated thumbnails use Chameleon-compatible naming and directory sharding
• files are reused when present and up to date
• files are regenerated only when missing or older than their source
• request-local caches avoid repeated checks in one request

Format Handlers

Handlers implement ChameleonSystem\ImageFormatBundle\Format\FormatHandlerInterface.

Current built-in handler:

• ChameleonSystem\ImageFormatBundle\Format\WebpFormatHandler

To add another format:

1. Implement FormatHandlerInterface
2. Implement getFormat(), canBeUsed(), supportsSourceType(), and createThumbnail()
3. Register the service and tag it with:

   <tag name="chameleon_system_image_format.format_handler"/>
   

4. Add the format to active_formats
5. Add the handler-specific config under format_settings.<format>

Notes

• TPkgSnippetRendererFilter::getThumbnail() remains unchanged
• after changing service wiring or configuration, rebuild the Symfony container
• the runtime environment must provide the encoder support required by the active handler